ReferenceCommands
CLI command reference
Every orbits command and subcommand, with its usage, what it does, and its flags, from the CLI's own help.
Every command the Orbits CLI has, as orbits <command> --help prints it. Run that for the same text in your terminal.
Global flags
These work on every command.
| Flag | What it does |
|---|---|
--json | print JSON instead of a table |
-p, --profile <string> | profile to use (default: the current one) |
--project <string> | project slug or prj_ id (default: the folder's linked project) |
-q, --quiet | print only ids |
--team <string> | team slug or team_ id (default: the linked project's, else the profile's) |
-y, --yes | do not ask before changes that delete something or change production |
orbits link
Tie this folder to an Orbits project, so commands run in it (or below it) use that project: orbits deploy, logs, env and the rest. The link is .orbits/project.json, and .orbits is added to .gitignore.
Without a project, pick one from the team's list (or make a new one). With --create, make a new upload project named after the argument or the folder.
orbits link [project] [flags]$ orbits link$ orbits link storefront$ orbits link --create$ orbits --team acme link storefront| Flag | What it does |
|---|---|
--create | make a new upload project and link it |
orbits login
Sign in through the Orbits web app in your browser. You choose the team, the access (full, or read only) and how long it lasts there, and the CLI receives an API token for that team, which is stored in your system's keychain. The team becomes this profile's default.
A token acts inside one team. To work in several, sign in once per team with a profile each: orbits --profile <name> login, then orbits teams switch.
Without a browser (a server, CI), make a token under Team › Settings › API tokens and pass it on stdin:
orbits login --with-token < token.txtor store nothing and set ORBITS_TOKEN.
orbits login [flags]$ orbits login$ orbits --profile acme login$ echo "$ORBITS_TOKEN" | orbits login --with-token| Flag | What it does |
|---|---|
--no-browser | print the sign-in link instead of opening a browser |
--with-token | read an API token from stdin instead of signing in in a browser |
orbits logout
Sign out: forget this profile's token on this machine. The token keeps working until it expires or is revoked under Team › Settings › API tokens (API tokens can't revoke themselves).
ORBITS_TOKEN is never touched: unset it yourself.
orbits logout [flags]$ orbits logout$ orbits --profile acme logoutorbits unlink
Remove this folder's link to a project
orbits unlink [flags]orbits whoami
Show who and which team the CLI acts as
orbits whoami [flags]orbits deploy
Deploy the linked project (or --project) and follow the build.
An upload project takes the folder (default: this one) as its source: it is zipped, leaving out node_modules, .git, .next, .orbits, .env*.local files and the patterns in .orbitsignore (.gitignore syntax), sent, and built. Uploads go straight to production.
A Git project builds a branch's newest commit: --prod for the production branch, --branch for a preview of another. Pushing to the repository deploys too; "orbits deployments redeploy" builds an existing deployment again.
The build's steps and log are shown as it runs, on stderr, and the address is printed on stdout when it is ready. A failed build exits with code 5.
orbits deploy [dir] [flags]$ orbits deploy$ orbits deploy ./dist$ orbits deploy --prod$ orbits deploy --branch feature/checkout$ url=$(orbits deploy --no-logs)| Flag | What it does |
|---|---|
--branch <string> | for a Git project: build this branch's newest commit (a preview, unless it is the production branch) |
--no-logs | show the build's steps but not its log lines |
--no-wait | print the deployment's id once it is queued, without following the build |
--prod | deploy to production (a Git project's production branch; uploads always are) |
orbits deployments
List and show deployments; promote, roll back, redeploy and cancel them
orbits deployments [command]Also: deployment, dpl.
| Command | What it does |
|---|---|
orbits deployments cancel | Stop a queued or building deployment |
orbits deployments get | Show a deployment (default: the newest) |
orbits deployments list | List the project's deployments, newest first |
orbits deployments promote | Rebuild a preview for production; it goes live when ready |
orbits deployments redeploy | Build a deployment's commit (or upload) again (default: production's) |
orbits deployments rollback | Point production at an earlier production deployment, at once |
orbits deployments cancel
Stop a queued or building deployment
orbits deployments cancel <deployment> [flags]orbits deployments get
Show a deployment (default: the newest)
orbits deployments get [deployment] [flags]Also: show, inspect.
orbits deployments list
List the project's deployments, newest first
orbits deployments list [flags]Also: ls.
| Flag | What it does |
|---|---|
--branch <string> | only this branch's |
--environment <string> | production or preview |
--limit <int> | at most this many (default 20) |
--state <string> | queued, building, ready, failed or canceled |
orbits deployments promote
Rebuild a preview for production; it goes live when ready
orbits deployments promote <deployment> [flags]| Flag | What it does |
|---|---|
--no-wait | do not follow the build |
orbits deployments redeploy
Build a deployment's commit (or upload) again (default: production's)
orbits deployments redeploy [deployment] [flags]| Flag | What it does |
|---|---|
--no-cache | build without the build cache |
--no-wait | do not follow the build |
orbits deployments rollback
Point production at an earlier production deployment straight away, with no rebuild (default: the one before the current one). Automatic production deploys pause until a promote, so the next push does not replace it.
orbits deployments rollback [deployment] [flags]orbits logs
Show a deployment's build log (default: the newest deployment's); -f follows a build that is still running until it ends, and exits 5 if it fails.
--runtime shows what the running project logs instead: requests and function output, newest last; -f keeps printing new entries.
orbits logs [deployment] [flags]$ orbits logs$ orbits logs dpl_123 -f$ orbits logs --runtime --since 24h --level error$ orbits logs --runtime -f --source functions| Flag | What it does |
|---|---|
-f, --follow | keep printing new lines |
--level <string> | with --runtime: info, warning or error |
--limit <int> | with --runtime: at most this many entries (default 100) |
--runtime | the running project's logs, not a build's |
--search <string> | with --runtime: a path, message, status, method or request id |
--since <string> | with --runtime: 1h (default), 24h or 7d |
--source <string> | with --runtime: requests or functions |
-t, --timestamps | show each build line's time |
orbits open
Open the project in the web app (or its site, with --site)
orbits open [project] [flags]| Flag | What it does |
|---|---|
--print | print the address instead of opening it |
--site | open the production site instead |
orbits projects
List, show, create, delete, pause and resume projects
orbits projects [command]Also: project.
| Command | What it does |
|---|---|
orbits projects create | Make a project: an upload project, or one built from a GitHub repository |
orbits projects delete | Delete a project, its deployments, variables and flags |
orbits projects get | Show a project (default: the linked one) |
orbits projects list | List the team's projects, most recently deployed first |
orbits projects pause | Stop serving a project (its address answers that it is paused) |
orbits projects resume | Serve a paused project again |
orbits projects create
Make a project. Without --repo it is an upload project, deployed with "orbits deploy" from a folder; with --repo, Orbits builds the repository on every push (the team's GitHub must be connected in the web app).
orbits projects create <name> [flags]$ orbits projects create storefront$ orbits projects create docs --workload static --output-dir dist --spa$ orbits projects create api --repo acme/api --branch main| Flag | What it does |
|---|---|
--branch <string> | with --repo: the production branch (default "main") |
--output-dir <string> | for a static site: the folder the build writes |
--region <string> | region (default: abj-1) |
--repo <string> | build this GitHub repository, owner/name |
--root <string> | with --repo: the folder in the repository to build |
--spa | for a static site: serve index.html for paths with no file |
--workload <string> | static, function, worker, app or container (default: detected) |
orbits projects delete
Delete a project, its deployments, variables and flags
orbits projects delete <project> [flags]Also: rm.
orbits projects get
Show a project (default: the linked one)
orbits projects get [project] [flags]Also: show.
orbits projects list
List the team's projects, most recently deployed first
orbits projects list [flags]Also: ls.
| Flag | What it does |
|---|---|
--limit <int> | at most this many (default: all) |
--search <string> | only projects whose name matches |
orbits projects pause
Stop serving a project (its address answers that it is paused)
orbits projects pause [project] [flags]orbits projects resume
Serve a paused project again
orbits projects resume [project] [flags]orbits domains
Manage the team's domains and their DNS records
orbits domains [command]Also: domain.
| Command | What it does |
|---|---|
orbits domains add | Add a domain to the linked project (or --project) |
orbits domains ls | List domains: the linked project's, or the team's with --all |
orbits domains records | Manage the DNS records of a domain on Orbits DNS |
orbits domains rm | Remove a domain from the team |
orbits domains verify | Check a domain's DNS now, and say what it still needs |
orbits domains add
Add a domain. It serves the linked project's production (or --project's), a branch's newest preview with --branch, or redirects with --redirect-to. With --no-project it is only added to the team.
Then point its DNS where "orbits domains verify" says, or use Orbits DNS (--dns orbits) and set the nameservers it names at your registrar.
orbits domains add <domain> [flags]$ orbits domains add shop.example.com$ orbits domains add staging.example.com --branch staging$ orbits domains add www.example.com --redirect-to example.com$ orbits domains add example.com --dns orbits| Flag | What it does |
|---|---|
--branch <string> | serve this branch's newest ready preview instead of production |
--dns <string> | external (default: keep your DNS provider) or orbits (Orbits DNS) |
--no-project | add the domain to the team without a project |
--redirect-to <string> | redirect every request to this hostname instead of serving a project |
orbits domains ls
List domains: the linked project's, or the team's with --all
orbits domains ls [flags]Also: list.
| Flag | What it does |
|---|---|
--all | every domain of the team, not only the linked project's |
orbits domains records
Manage the DNS records of a domain on Orbits DNS
orbits domains records [command]Also: dns.
| Command | What it does |
|---|---|
orbits domains records add | Add a record: A, AAAA, CNAME, MX, TXT or CAA |
orbits domains records ls | List a zone's records |
orbits domains records rm | Remove a record |
orbits domains records add
Add a record to a zone on Orbits DNS. The name is relative to the zone (@ for the apex). An MX record's value is its priority and server; a TXT record's is its text without quotes.
orbits domains records add <domain> <type> <name> <value> [flags]$ orbits domains records add example.com A @ 203.0.113.10$ orbits domains records add example.com MX @ "10 mail.example.com"$ orbits domains records add example.com TXT _verify "token-from-the-provider" --ttl 300| Flag | What it does |
|---|---|
--ttl <int> | seconds: 0 (auto, 5 minutes), 60, 300, 3600 or 86400 |
orbits domains records ls
List a zone's records
orbits domains records ls <domain> [flags]Also: list.
orbits domains records rm
Remove a record
orbits domains records rm <domain> <record id> [flags]Also: remove, delete.
orbits domains rm
Remove a domain from the team
orbits domains rm <domain> [flags]Also: remove, delete.
orbits domains verify
Check a domain's DNS now, and say what it still needs
orbits domains verify <domain> [flags]Also: check, inspect.
orbits env
Manage the project's environment variables. Values are never printed unless you ask (ls --show-values, pull): a sensitive variable is write-only, and nobody can read it back. Reading values needs a full-access token.
A changed variable takes effect on the next deployment.
orbits env [command]| Command | What it does |
|---|---|
orbits env add | Add a variable (or replace one, with --force) |
orbits env ls | List the variables: keys, environments, sensitive or not |
orbits env pull | Write the variables to a dotenv file (default .env.local) |
orbits env restore | Bring back a variable removed recently |
orbits env rm | Remove a variable (restorable for a while) |
orbits env add
Add a variable. Without a value on the command line it is read from stdin: typed hidden at a terminal, or piped, which keeps it out of your shell's history.
Variables are sensitive (write-only) unless --plain: a sensitive value can be replaced but never read back, not even by orbits env pull.
orbits env add <KEY> [value] [flags]Also: set.
$ orbits env add DATABASE_URL$ printf %s "$STRIPE_KEY" | orbits env add STRIPE_KEY --environment production$ orbits env add NEXT_PUBLIC_SITE_NAME Storefront --plain$ orbits env add API_URL https://api.example.com --force| Flag | What it does |
|---|---|
--environment <string> | comma-separated: production, preview, development (default: production, preview) |
--force | replace the variable if it exists |
--plain | not sensitive: the value can be read back (and pulled) |
orbits env ls
List the variables: keys, environments, sensitive or not
orbits env ls [flags]Also: list.
| Flag | What it does |
|---|---|
--environment <string> | only variables used by production, preview or development |
--show-values | print values too (sensitive ones are write-only) |
orbits env pull
Write an environment's variables (default: development) to a dotenv file, readable only by you (mode 0600). Sensitive variables are write-only, so they are left out and named. Replacing an existing file asks first.
It needs a full-access token: reading values is a change only full tokens may make.
orbits env pull [file] [flags]$ orbits env pull$ orbits env pull .env.production.local --environment production| Flag | What it does |
|---|---|
--environment <string> | production, preview or development (default "development") |
orbits env restore
Bring back a variable removed recently
orbits env restore <KEY> [flags]orbits env rm
Remove a variable (restorable for a while)
orbits env rm <KEY> [flags]Also: remove, delete.
orbits flags
Manage the project's feature flags
orbits flags [command]Also: flag.
| Command | What it does |
|---|---|
orbits flags create | Make a flag: boolean (default), string or number |
orbits flags get | Show a flag, its rules and history |
orbits flags ls | List the flags and their state in each environment |
orbits flags rm | Delete a flag and its history |
orbits flags rules | Add and remove a flag's targeting rules |
orbits flags set | Change a flag in one environment: on, off, rollout or value |
orbits flags create
Make a flag: boolean (default), string or number
orbits flags create <key> [flags]| Flag | What it does |
|---|---|
--description <string> | what the flag is for |
--type <string> | boolean, string or number (default "boolean") |
orbits flags get
Show a flag, its rules and history
orbits flags get <key> [flags]Also: show.
orbits flags ls
List the flags and their state in each environment
orbits flags ls [flags]Also: list.
orbits flags rm
Delete a flag and its history
orbits flags rm <key> [flags]Also: remove, delete.
orbits flags rules
Add and remove a flag's targeting rules
orbits flags rules [command]| Command | What it does |
|---|---|
orbits flags rules add | Serve a value to visitors who match a rule |
orbits flags rules rm | Remove a rule |
orbits flags rules add
Serve a value to visitors who match a rule
orbits flags rules add <key> [flags]$ orbits flags rules add new-checkout --environment production --attribute email --operator ends_with --values @example.com --serve true| Flag | What it does |
|---|---|
--attribute <string> | the visitor attribute to match, such as email or country (required) |
--environment <string> | production, preview or development (required) |
--operator <string> | equals, not_equals, one_of, ends_with, starts_with or contains (default "equals") |
--serve <string> | what matching visitors get: true, false, a number or text (default "true") |
--values <string> | comma-separated values to match (required) |
orbits flags rules rm
Remove a rule
orbits flags rules rm <key> <rule id> [flags]| Flag | What it does |
|---|---|
--environment <string> | production, preview or development (required) |
orbits flags set
Change a flag in one environment: on, off, rollout or value
orbits flags set <key> [flags]$ orbits flags set new-checkout --environment production --on --rollout 25$ orbits flags set new-checkout --environment production --off$ orbits flags set banner-text --environment preview --value "Free shipping"| Flag | What it does |
|---|---|
--environment <string> | production, preview or development (required) |
--off | turn a boolean flag off |
--on | turn a boolean flag on |
--rollout <int> | the percentage of visitors who get it (default 100) |
--value <string> | a string or number flag's value |
orbits teams
A token acts inside one team, so each team you work in has its own profile: sign in to another with "orbits --profile <name> login", choosing the team in the browser, then switch between them with "orbits teams switch".
orbits teams [command]| Command | What it does |
|---|---|
orbits teams list | List your teams: one per signed-in profile |
orbits teams switch | Make the profile signed in to a team the current one |
orbits teams list
List your teams: one per signed-in profile
orbits teams list [flags]Also: ls.
orbits teams switch
Make the profile signed in to a team (by slug, team_ id or profile name) the one commands use when --profile is not given.
orbits teams switch <team> [flags]$ orbits teams switch acmeorbits activity
Show what happened in the team (or the linked project)
orbits activity [flags]$ orbits activity$ orbits activity --all --since 72h| Flag | What it does |
|---|---|
--all | the whole team, not only the linked project |
--limit <int> | at most this many (default 50) |
--since <string> | how far back, such as 24h (default: 7 days; at most 90) |
orbits alerts
Manage the project's alerts: error rate, latency, traffic
orbits alerts [command]Also: alert.
| Command | What it does |
|---|---|
orbits alerts create | Make an alert |
orbits alerts disable | Switch an alert off |
orbits alerts enable | Switch an alert on |
orbits alerts events | List when an alert fired and resolved |
orbits alerts ls | List the project's alerts |
orbits alerts rm | Delete an alert |
orbits alerts create
Make an alert
orbits alerts create <name> [flags]$ orbits alerts create "Errors" --metric error-rate --threshold 5 --window 5$ orbits alerts create "Slow" --metric p99 --threshold 1500 --routes "/api/*"$ orbits alerts create "Quiet" --metric requests --direction below --threshold 10 --window 30| Flag | What it does |
|---|---|
--channels <string> | comma-separated: email, webhook (default "email") |
--direction <string> | above, or below (requests only) (default "above") |
--metric <string> | error-rate (%), p75 or p99 (ms), or requests (required) |
--routes <string> | comma-separated routes (a trailing * matches a prefix; default: all) |
--threshold <float> | the value that fires it (required) |
--window <int> | minutes measured: 1, 5, 10 or 30 (default 5) |
orbits alerts disable
Switch an alert off
orbits alerts disable <alert id> [flags]orbits alerts enable
Switch an alert on
orbits alerts enable <alert id> [flags]orbits alerts events
List when an alert fired and resolved
orbits alerts events <alert id> [flags]orbits alerts ls
List the project's alerts
orbits alerts ls [flags]Also: list.
orbits alerts rm
Delete an alert
orbits alerts rm <alert id> [flags]Also: remove, delete.
orbits completion
Generate the autocompletion script for orbits for the specified shell. See each sub-command's help for details on how to use the generated script.
orbits completion [command]| Command | What it does |
|---|---|
orbits completion bash | Generate the autocompletion script for bash |
orbits completion fish | Generate the autocompletion script for fish |
orbits completion powershell | Generate the autocompletion script for powershell |
orbits completion zsh | Generate the autocompletion script for zsh |
orbits completion bash
Generate the autocompletion script for the bash shell.
This script depends on the 'bash-completion' package. If it is not installed already, you can install it via your OS's package manager.
To load completions in your current shell session:
source <(orbits completion bash)To load completions for every new session, execute once:
Linux:
orbits completion bash > /etc/bash_completion.d/orbitsmacOS:
orbits completion bash > $(brew --prefix)/etc/bash_completion.d/orbitsYou will need to start a new shell for this setup to take effect.
orbits completion bash| Flag | What it does |
|---|---|
--no-descriptions | disable completion descriptions |
orbits completion fish
Generate the autocompletion script for the fish shell.
To load completions in your current shell session:
orbits completion fish | sourceTo load completions for every new session, execute once:
orbits completion fish > ~/.config/fish/completions/orbits.fishYou will need to start a new shell for this setup to take effect.
orbits completion fish [flags]| Flag | What it does |
|---|---|
--no-descriptions | disable completion descriptions |
orbits completion powershell
Generate the autocompletion script for powershell.
To load completions in your current shell session:
orbits completion powershell | Out-String | Invoke-ExpressionTo load completions for every new session, add the output of the above command to your powershell profile.
orbits completion powershell [flags]| Flag | What it does |
|---|---|
--no-descriptions | disable completion descriptions |
orbits completion zsh
Generate the autocompletion script for the zsh shell.
If shell completion is not already enabled in your environment you will need to enable it. You can execute the following once:
echo "autoload -U compinit; compinit" >> ~/.zshrcTo load completions in your current shell session:
source <(orbits completion zsh)To load completions for every new session, execute once:
Linux:
orbits completion zsh > "${fpath[1]}/_orbits"macOS:
orbits completion zsh > $(brew --prefix)/share/zsh/site-functions/_orbitsYou will need to start a new shell for this setup to take effect.
orbits completion zsh [flags]| Flag | What it does |
|---|---|
--no-descriptions | disable completion descriptions |
orbits mcp
Connect AI apps to Orbits through the Model Context Protocol (MCP), so they can list, deploy and manage your projects for you.
The hosted server (https://mcp.theorbits.app/mcp) is the default: the app opens your browser and you approve it in the web app, choosing its team and access. With --local the app runs orbits-mcp on this machine instead, with your signed-in profile or ORBITS_TOKEN.
orbits mcp [command]| Command | What it does |
|---|---|
orbits mcp install | Add Orbits to an AI app |
orbits mcp list-clients | List the AI apps orbits mcp install can set up |
orbits mcp status | Show the hosted server, whether orbits-mcp is installed, and which apps have Orbits |
orbits mcp install
Add Orbits to an AI app
The AI apps it can set up, and what it does for each, are on Connect your AI app.
orbits mcp install <client> [flags]| Flag | What it does |
|---|---|
--local | run orbits-mcp on this machine instead of using the hosted server |
--print | print the config instead of changing anything |
--url <string> | use another hosted server URL (default https://mcp.theorbits.app/mcp) |
orbits mcp list-clients
List the AI apps orbits mcp install can set up
orbits mcp list-clients [flags]orbits mcp status
Show the hosted server, whether orbits-mcp is installed, and which apps have Orbits
orbits mcp status [flags]orbits sandboxes
Start, stop and remove the project's sandboxes
orbits sandboxes [command]Also: sandbox, sb.
| Command | What it does |
|---|---|
orbits sandboxes create | Start a new sandbox |
orbits sandboxes ls | List the project's sandboxes |
orbits sandboxes rm | Delete a sandbox and its files |
orbits sandboxes start | Start a stopped sandbox |
orbits sandboxes stop | Stop a sandbox (it keeps its files) |
orbits sandboxes create
Start a new sandbox
orbits sandboxes create <name> [flags]$ orbits sandboxes create try-upgrade --runtime node22 --clone --env| Flag | What it does |
|---|---|
--clone | check out the project's repository at main |
--env | copy the Preview environment variables in |
--runtime <string> | node22, python312 or go123 (default "node22") |
--size <string> | small or large (default "small") |
--stop-after <int> | idle minutes before it suspends: 10, 30, 60 or 120 (default 30) |
orbits sandboxes ls
List the project's sandboxes
orbits sandboxes ls [flags]Also: list.
orbits sandboxes rm
Delete a sandbox and its files
orbits sandboxes rm <name> [flags]Also: remove, delete.
orbits sandboxes start
Start a stopped sandbox
orbits sandboxes start <name> [flags]orbits sandboxes stop
Stop a sandbox (it keeps its files)
orbits sandboxes stop <name> [flags]orbits update
Install the latest version of the CLI, or the version given, in place of this one, from its GitHub releases. The download is checked against the release's checksums.txt first. A CLI installed with Homebrew is upgraded with brew instead.
The CLI says when a newer version is out, at most once a day. Set ORBITS_NO_UPDATE_NOTIFIER=1 to turn that off.
orbits update [version] [flags]Also: upgrade.
$ orbits update$ orbits update --check$ orbits update v0.2.0| Flag | What it does |
|---|---|
--check | only print the latest version |
orbits usage
Show the team's usage this month (or --month), by project
orbits usage [flags]$ orbits usage$ orbits usage --month 2026-10| Flag | What it does |
|---|---|
--month <string> | a past month, YYYY-MM (default: this one) |
orbits version
Print the CLI's version
orbits version [flags]orbits workflows
List workflows and their runs; run, cancel and retry them
orbits workflows [command]Also: workflow, wf.
| Command | What it does |
|---|---|
orbits workflows cancel | Cancel a running workflow run |
orbits workflows ls | List the project's workflows |
orbits workflows retry | Run a failed workflow run again |
orbits workflows run | Start a workflow now |
orbits workflows runs | List recent runs, or show one |
orbits workflows cancel
Cancel a running workflow run
orbits workflows cancel <run id> [flags]orbits workflows ls
List the project's workflows
orbits workflows ls [flags]Also: list.
orbits workflows retry
Run a failed workflow run again
orbits workflows retry <run id> [flags]orbits workflows run
Start a workflow now
orbits workflows run <workflow> [flags]$ orbits workflows run send-digest --input '{"week":45}'| Flag | What it does |
|---|---|
--input <string> | the JSON the run starts with |
orbits workflows runs
List recent runs, or show one
orbits workflows runs [run id] [flags]| Flag | What it does |
|---|---|
--workflow <string> | only this workflow's runs |