orion-cli

Operate Orion source control and Orion Cloud from the terminal:

orion-cli deploy

That is the whole thing. The first run creates the cloud repo, pushes your code, queues a server-side build, waits for it, and prints the live URL. Every later run in the same clone updates the same app.

Zero runtime dependencies. Node 20+.

Read the CLI documentation for a task-oriented human guide and a compact agent operating contract.

Install

bun add --global orion-cloud
# or, without installing:
bunx orion-cloud deploy

Sign in

orion-cli login

Opens your browser, signs in through Orion Cloud, and hands the token back to a loopback listener on 127.0.0.1 (an OAuth-style PKCE authorization-code flow — the same one Orion Desktop uses). The token is verified before it is written.

For headless machines, CI, and agents:

orion-cli login --token <token>     # verified, then saved
export ORION_TOKEN=<token>          # or skip the file entirely

--token and ORION_TOKEN both accept an Orion desktop session token or a personal access token (orion_pat_…).

orion-cli whoami     # who the saved token belongs to
orion-cli logout     # clear this machine's saved credentials

logout clears credentials locally. There is no CLI revoke endpoint, so the token itself stays valid until it expires — manage sessions on the web.

Commands

| Command | What it does | | --- | --- | | orion-cli deploy | Push the current app and deploy it | | orion-cli source | Inspect or switch source control to Orion and manage GitHub mirroring | | orion-cli pr | Create, inspect, check out, update, and merge pull requests | | orion-cli service | List, provision, configure, status, or deploy managed services | | orion-cli environment | List, create, or delete Cloud environments | | orion-cli preview | Show or configure preview-environment policy | | orion-cli activity / logs | Inspect root-app or managed-service deployments | | orion-cli list | Every repo this token can reach, with app status and URLs | | orion-cli repo | Create, configure, or safely delete repositories | | orion-cli collaborator | Manage repository collaborators and roles | | orion-cli status | Deploy state of the app linked to this folder | | orion-cli open | Open the deployed app in your browser | | orion-cli configure | Show or set monorepo/build configuration | | orion-cli env | List, set, or remove Orion Cloud environment variables | | orion-cli domain | List, add, select the primary, or remove custom domains | | orion-cli bucket | List, create, or safely delete object storage buckets | | orion-cli resources | List or sync managed resources on the Cloud canvas | | orion-cli plan | Publish an HTML plan and print its share link | | orion-cli login | Sign in (browser, or --token) | | orion-cli logout | Clear saved credentials | | orion-cli whoami | Show the signed-in account |

Share a plan

When a user asks for a plan that benefits from a richer visual format, write it as a self-contained HTML file and publish it through the signed-in Orion account:

orion-cli plan upload ./plan.html
orion-cli plan upload ./plan.html --json

The command prints the unlisted public https://plan.orioncode.xyz/p/... link. JSON mode returns { "ok": true, "id": "...", "url": "..." }. Plans are public to anyone with the link, so do not include credentials or private data. Agents should use this only when the user explicitly requests a plan, and must include the returned link in their response after uploading.

deploy

--project <repo-id>   Deploy into a specific cloud repo (see `orion-cli list`)
--name <name>         Name for a newly created cloud repo
--path <dir>          App directory (default: current directory)
--no-push             Deploy what the cloud repo already has; skip pushing
--json                One machine-readable JSON line instead of prose
--root <dir>          Monorepo root directory
--build-command <cmd> Override the build command
--start-command <cmd> Override the start command
--healthcheck <path>  Health-check path (must start with /)
--environment <slug>  Target environment (default: production)
--env-file <file>     Dotenv file to sync before deploy; repeatable
--no-env-sync         Leave the Orion vault unchanged

What it does, in order:

1. Finds a git repo. Not a repo yet? It runs git init and makes the first commit. No commits yet? It commits. Uncommitted changes? It warns that they will not be deployed and continues with HEAD — it never blocks.
2. Resolves the cloud repo. --project wins; otherwise the link recorded in the local git config (orion.cloudrepoid); otherwise it creates one, named from --name, else package.json's name, else the folder name.
3. Pushes HEAD to the cloud repo.
4. Syncs local environment files to the selected encrypted Orion vault. By default it safely merges existing .env, .env.local, and .env.<environment> files; later files win. Use repeatable --env-file flags to choose exact files, or --no-env-sync to opt out. Values never enter git, command-line arguments, or CLI output.
5. Queues the build and polls until it is deployed or failed (up to 20 minutes — first builds are slow), then prints the app URL and the manage URL.

Exit code is 0 only when the app reaches deployed.

Cloud configuration

The same settings available in Orion Cloud are agent-friendly CLI commands:

orion-cli configure --root orion-next --build-command "bun run build"
orion-cli env push .env.production --environment production
orion-cli env push --environment development
orion-cli env list --environment production
printf '%s' "$API_KEY" | orion-cli env set API_KEY --stdin --environment production
orion-cli env reveal API_KEY --environment production
orion-cli env environments
orion-cli repo list
orion-cli repo create my-app --default-branch main
orion-cli repo configure my-app --visibility private --description "My app"
orion-cli collaborator add @teammate --project my-app --role write
orion-cli collaborator role @teammate --project my-app --role admin
orion-cli collaborator remove @teammate --project my-app --yes
orion-cli repo delete my-app --yes
orion-cli domain add example.com --json
orion-cli domain primary example.com
orion-cli domain add api.example.com --service api
orion-cli domain list --service railway:api --json
orion-cli bucket list --json
orion-cli bucket create my-app-assets
orion-cli bucket delete my-app-assets --yes
orion-cli resources sync infrastructure.json

Environment values are encrypted in an environment-specific Orion vault: env list returns names, never values. Environment-scoped single-value writes require --stdin, while env push [file] is best for bulk sync; neither puts plaintext values in process arguments. env reveal is explicit and prints the plaintext value, so redirect or capture it carefully. Orion owns and operates the underlying infrastructure, and resources synced to the canvas must be credential-free metadata. bucket list refreshes the app's managed object storage on the canvas. Buckets currently configured as Orion release or repository storage cannot be deleted; all other deletes require --yes and the bucket must already be empty.

repo create provisions a private Orion repository without deploying it or linking the current directory. repo delete accepts an exact name or id, is owner-only, and requires --yes. The CLI refuses to delete repositories that still have an Orion Cloud app so provider services cannot be orphaned.

domain targets the app workload by default. Pass --service <name-or-id> to manage a service card instead; Orion returns the Railway CNAME and TXT verification details and keeps that service's primary URL in sync.

Source-control conversion

orion-cli source status
orion-cli source use-orion
orion-cli source mirror status
orion-cli source mirror authorize
orion-cli source mirror disconnect

source use-orion is the CLI equivalent of Orion Desktop's source-control switch. It refreshes all GitHub branches and tags, creates or reuses the Orion repository, atomically imports the refs, changes origin to Orion, preserves GitHub as the github remote, and begins continuous mirroring. Divergent local refs are retained under collision-safe orion-local/* names. Tokens are passed to Git through a short-lived askpass helper and are never stored in remote URLs. Use --no-github-mirror if conversion should not begin mirror authorization.

Pull requests

The pull-request workflow is designed for both humans and coding agents:

orion-cli pr list
orion-cli pr view 5
orion-cli pr create --title "Add repository stars" --body "Ready for review"
orion-cli pr checkout 5
orion-cli pr update-branch 5
orion-cli pr push 5
orion-cli pr merge 5 --merge
orion-cli pr close 5
orion-cli pr reopen 5

pr view reports the pinned base/head commits, file summary, mergeability, and exact conflict paths. pr checkout fetches the PR's pinned head commit rather than trusting a named ref fetch, so it also works with branch names that the Orion Git smart-HTTP server advertises but cannot fetch directly.

pr update-branch checks out the PR branch, merges its current base, and pushes the result when clean. If Git finds conflicts, it leaves the merge in progress and prints the paths to resolve; after committing the resolution, pr push updates the exact PR head branch. pr merge supports merge commits by default and --squash. Every command supports --json for agent-safe output.

Managed Cloud services and environments

orion-cli service list
orion-cli service create api --root services/api --inherit DATABASE_URL
orion-cli service configure api --no-deploy-on-push
orion-cli service deploy api
orion-cli activity --service api
orion-cli logs <deployment-id> --service api --stream build

orion-cli environment create Staging --slug staging
orion-cli environment delete staging --yes
orion-cli preview status
orion-cli preview configure --enable --branch-previews --ttl 48

Service creation uses the same Orion provisioning handler as the Cloud canvas. Pass repeatable --env-file flags to supply service-only variables and repeatable --inherit flags for root-app variables. The first deployment is an explicit service deploy; that command waits for a terminal deployment state. Orion provisions the normal apps-domain subdomain for each public workload; use domain add ... (and --service for a service card) to attach custom domains.

status / open

Both act on the repo linked to the current folder, or --project <repo-id>. Both accept --path <dir>. status takes --json.

For coding agents

One shot, from the app directory:

git add -A && git commit -m "…"      # uncommitted changes are not deployed
orion-cli deploy --json

The last stdout line is a single JSON object:

{
  "ok": true,
  "origin": "https://orioncode.xyz",
  "repoId": "abc123…",
  "repoName": "my-app",
  "environment": "production",
  "branch": "main",
  "commit": "7851e39cedefb6089b6ee09b2f516c3c6252b8f8",
  "status": "deployed",
  "url": "https://my-app-abc123.andromedus.dev",
  "manageUrl": "https://orioncode.xyz/repos/abc123…",
  "pushed": ["main"],
  "error": null
}

• ok is true only when status === "deployed"; the exit code matches (0 / 1).
• status is one of queued, building, deployed, failed — or error when the deploy could not be started at all.
• On failure, error holds the tail of the build log. On timeout, timedOut is true and status is whatever the build was still doing.
• Read the live app from url.

The command blocks until the build settles, so there is nothing to poll. If you do want to check later, orion-cli status --json and orion-cli list --json return the same shapes without deploying.

Headless: set ORION_TOKEN and skip login entirely. Everything works over bunx orion-cloud too.

Where things are stored

Credentials live in ~/.config/orion/credentials.json, mode 0600, as a JSON map keyed by origin — so a production login and a local dev login coexist in one file. ORION_TOKEN overrides the file entirely.

The repo → app link lives in the repository's local git config:

git config --local --get orion.cloudrepoid     # cloud repo id
git config --local --get orion.cloudreponame   # cloud repo name

These are the same keys Orion Desktop writes, so a clone linked by either client stays linked for both. Nothing is added to your working tree, and no token is ever written into .git/config or a remote URL.

Environment

| Variable | Meaning | | --- | --- | | ORION_ORIGIN | Orion Cloud origin (default https://orioncode.xyz) | | ORION_TOKEN | Bearer token; wins over saved credentials | | ORION_CONFIG_DIR | Credentials directory (default ~/.config/orion) | | ORION_NO_UPDATE_CHECK | Set to 1 to skip the daily new-version check | | NO_COLOR | Disable ANSI colors (also off when not a TTY) |

Development

bun install
bun run build      # tsc → dist/
bun run typecheck
node dist/index.js --help

License

MIT