julion init
Initializes Julion in the current project by creating .julion.json.
julion init julion init --from team-template
| Option | Meaning |
|---|---|
--from <template> | Restore from a template stored in ~/.julion/templates. |
Julion CLI 0.2
Documentation
Everything needed to install Julion, create a project snapshot, store it in Google Drive, inspect it, and restore it safely.
What Julion does
Julion converts a software project into one .on snapshot. A snapshot contains the selected project files, metadata, checksums, and information needed after restoration. You can keep it locally, encrypt it, upload it to your own Google Drive, inspect it through the CLI or dashboard, and export it as a standard ZIP.
Important:
.on is Julion's format, not a ZIP file. Use julion restore or julion export --format zip.Install the VS Code or Cursor extension
Install the CLI before the extension, then completely restart the editor so its extension host sees the npm installation.
npm install --global julion@latest julion --version code --install-extension julion-vscode-0.2.4.vsix --force
For Cursor, use:
cursor --install-extension julion-vscode-0.2.4.vsix --force cursor --list-extensions --show-versions
- Open a project folder.
- Open the Julion Activity Bar view.
- Select Connect Google Drive and finish browser login.
- Select Initialize.
- Select Connect repository.
Downloading a VSIX does not install it. Cursor must install the local file explicitly. If the icon is hidden, right-click the Activity Bar and enable Julion.
Windows CLI detection
Julion normally resolves %APPDATA%\npm\node_modules\julion\dist\index.js. If detection fails, set julion.cliPath to that JavaScript file—not to julion.cmd—and reload the editor.
Recover into an empty folder
- Open the empty destination folder in VS Code or Cursor.
- Select Browse Drive snapshots.
- Choose the Drive repository and snapshot.
- Run Preview recovery, then choose Recover native files.
Julion extracts the original project files into the open folder. The restored project is not left as a .on file.
Requirements
- Node.js 20 or newer.
- npm available in your terminal.
- A Google account only if you want Drive upload and the web dashboard.
- Permission to read the project and write the destination folder.
Check Node and npm
node --version npm --version
Install
npm install --global julion julion --version julion --help
The global installation makes the julion command available in any project folder.
Update later
npm install --global julion@latest
Login
Recommended: hosted browser login
julion login google --website
Your browser opens. Sign in with Google, approve Drive access, then return to the terminal. Julion never downloads the hosted application's Google client secret.
Use your own Google OAuth client
julion login google
On first use, the terminal asks for your Google Client ID, Client Secret, and Redirect URI. This mode is intended for self-hosted or direct developer access.
Your first backup
cd path/to/your-project julion init julion backup --ultra --report --out project.on
init marks the current folder as a Julion project. backup creates project.on. The safe default excludes dependencies, logs, build output, Git history, and .env.
Back up and upload
julion backup --ultra --report --deposit --repository my-project
Restore from Google Drive into an empty folder
This is the normal recovery workflow. Run it inside the empty folder where you want the native project files to appear. You do not need to run julion init.
mkdir restored-project cd restored-project julion login google --website julion pull my-project project.on --dry-run julion pull my-project project.on --force
- Replace
my-projectwith the repository folder shown in the dashboard. - Replace
project.onwith the exact snapshot name. - The dry run previews changes and writes nothing.
- The final command extracts native files directly into the current folder.
Important: do not add
--archive-only when you want restored files. That option deliberately downloads the .on container without extracting it.Update a project already stored in Google Drive
Run these commands from the project source folder after editing your files.
cd path/to/my-project julion backup --ultra --out project.on julion push project.on my-project
If project.on already exists in that Drive repository, Julion updates it. To preserve versions, choose a new filename such as project-v2.on. You can also create and upload in one step:
julion backup --ultra --deposit --repository my-project --out project.on
Restore from a local .on file
Use this only when the snapshot is already on your computer. Preview first; a dry run does not write files.
mkdir restored-project julion restore project.on ./restored-project --dry-run julion restore project.on ./restored-project --force
Julion extracts the native project files. After restoring, read the warnings; you may need to copy .env.example, install dependencies, or run julion boot --snapshot project.on.
Command reference
The clearer command names below are aliases. The older names remain compatible: begin, seal, unseal, deposit, fetch, info, and connect.
julion workspace
Connects the current project folder to one named repository inside My Drive / JULION. The non-secret binding is stored in .julion.json.
julion workspace connect client-portal julion workspace status julion workspace disconnect
After connecting, julion backup --ultra --deposit and julion deposit project.on use that repository automatically. Passing --repository another-name overrides the binding.
julion backup
Creates a snapshot of the current folder. Run it from the project root.
julion backup --ultra --report --out my-project.on julion backup --ultra --deposit --repository my-project
| Option | Meaning |
|---|---|
--ultra | Use the chunked, compressed V2 container. |
-o, --out <path> | Choose the snapshot filename. |
--deposit | Upload after creation. |
--repository <name> | Choose the Drive repository folder. |
--profile <name> | Use a predefined inclusion profile. |
--env structure | Include environment key names while redacting secret values. |
--env include | Include environment values. Use only with encryption. |
--report | Embed a project health report. |
--mirror | Include normally excluded files. Use carefully. |
--encrypt | Create an AES-256-GCM .vault.on snapshot. |
--passphrase <text> | Provide the vault passphrase non-interactively. Avoid shell history on shared machines. |
--notify <url> | Call a webhook after upload. |
--delta and --sign are intentionally disabled in 0.2. They fail instead of giving incomplete guarantees.julion restore <snapshot> [target]
Restores files from a local snapshot.
julion restore project.on ./project --dry-run julion restore project.on ./project --force julion restore project.on ./project --only src,package.json
| Option | Meaning |
|---|---|
--dry-run | Preview without writing. |
--force | Overwrite existing files. |
--only <paths> | Restore only comma-separated paths. |
--except <paths> | Skip comma-separated paths. |
--check | Check environment compatibility first. |
--passphrase | Unlock a vault snapshot. |
julion push <snapshot> [repository]
Uploads an existing snapshot to Google Drive.
julion push project.on my-project
If a snapshot with the same name exists, Julion updates it. Use clear versioned filenames when history matters.
julion pull <repository> <snapshot>
Downloads a snapshot from Drive and restores it.
julion pull my-project project-v4.on --out ./restored --dry-run julion pull my-project project-v4.on --archive-only --out project-v4.on
| Option | Meaning |
|---|---|
--archive-only | Download without restoring. |
--out <path> | Restore folder or downloaded archive path. |
--force | Overwrite restored files. |
--dry-run | Preview the restore. |
julion inspect [snapshot]
Prints manifest, boot information, health data, project map, and freeze information as JSON.
julion inspect project.on --json
julion export <snapshot>
Converts a Julion snapshot into a standard ZIP.
julion export project.on --format zip --out project.zip
julion verify <snapshot>
Checks snapshot integrity information. Detached authenticity signatures are not yet enabled in 0.2.
julion verify project.on
julion diff <old> <new>
Shows files added, removed, or modified between two snapshots.
julion diff project-v3.on project-v4.on
julion plan <snapshot> [target]
Creates the same safe restore preview without running restore.
julion plan project.on ./restored --force
julion boot
Reads the snapshot boot card and runs detected post-restore setup steps.
julion boot --snapshot project.on
Review a snapshot from an untrusted source before running boot steps. They can execute package installation and framework commands.
julion handoff
Creates a snapshot intended for another developer, with notes and ticket references.
julion handoff --notes "API complete; run migrations" --ticket DEV-142 --out handoff.on
julion profiles
Lists snapshot profiles such as default, Laravel deploy, Node CI, handoff, and client demo.
julion profiles julion backup --profile handoff --out handoff.on
julion search <query>
Searches filenames across local snapshots.
julion search UserController --path ./snapshots
julion open [name]
Opens a recently restored project from Julion's local recent-project list.
julion open julion open client-portal
julion serve <snapshot>
Extracts a snapshot into a temporary folder and runs its detected start command.
julion serve demo.on --port 4173
Use only with snapshots you trust.
julion schedule
Manages locally stored schedule definitions for recurring snapshots.
julion schedule list julion schedule add --cron "0 18 * * 1-5" --repository work --keep 10 julion schedule remove <id>
The host machine still needs a scheduler or active Julion process to execute schedules.
julion relay-export and julion import
Copies a snapshot with a metadata sidecar for offline transfer, then restores it on another machine.
julion relay-export project.on --out ./transfer julion import ./transfer --out ./restored
Encrypted vault snapshots
Use a vault when a backup must contain .env, credentials, dependencies, or other private material.
julion backup --mirror --env include --encrypt --out private.on julion restore private.vault.on ./restored --passphrase "your-passphrase" --dry-run
Prefer the interactive passphrase prompt so the passphrase does not remain in terminal history. Losing the passphrase means losing access to the snapshot.
Security model
- The hosted Google client secret stays on the server.
- OAuth state is one-time and expires after ten minutes.
- Drive tokens are encrypted before MongoDB storage.
- Browser sessions contain identity and role, not Drive tokens.
- Archive parsers enforce size and structure limits.
- Restore rejects unsafe absolute and parent paths.
- Admin permissions are checked server-side on every request.
Troubleshooting
julion is not recognized
Run npm config get prefix, add that folder to your system PATH, and restart the terminal.
Google says redirect URI mismatch
The URI must exactly match the callback registered in Google Cloud, including protocol, domain, path, and trailing slash behavior.
Google Drive is no longer connected
Run julion login google --website again. Hosted login does not install the application's secret on your computer.
A ZIP program cannot open .on
Use julion restore or export a ZIP with julion export.
Restore skipped files
Julion does not overwrite existing files unless you pass --force. Always review a dry run first.
Need command-specific help
julion --help julion backup --help julion restore --help