ReferenceCLI
The Orbits CLI
Deploy a folder or a branch and watch it build, read logs, and manage environment variables, domains, DNS, flags, workflows and alerts, from your terminal or from CI.
orbits drives your team's projects from the terminal, through the Orbits API. It runs on macOS and Linux, on both Intel/AMD (amd64) and ARM (arm64). There is no Windows build.
$ orbits login$ cd my-site && orbits link$ orbits deploy ✓ Packed 14 files 48 KB ✓ Uploaded 48 KB ✓ Queued 1s ✓ Installing 6s ✓ Building 12s ✓ Going live 2s✓ Ready in 23s (production)https://my-site.theorbits.appInstall
$ curl -fsSL https://orbits.africa/install | bashThe script downloads the build for your machine from the CLI's GitHub releases, checks it against the release's checksums.txt, puts it in ~/.orbits/bin and adds that to your PATH. Open a new terminal, or run the line it prints, then check it worked:
$ orbits --version- To install a particular version, pass it to the script:
curl -fsSL https://orbits.africa/install | bash -s -- v0.1.0. ORBITS_INSTALLinstalls somewhere other than~/.orbits.ORBITS_NO_MODIFY_PATH=1leaves your shell's startup file alone.
With Homebrew instead:
$ brew install The-Orbits/tap/orbitsWith npm, or pnpm, Yarn or Bun (Node.js 18 or later):
$ npm install -g @useorbits/cliThe package runs the same build as the other two, installed for your machine from one of its platform packages, such as @useorbits/cli-darwin-arm64. Keep optional dependencies on: with --omit=optional there is nothing to run. To run a command without installing, use npx @useorbits/cli, as in npx @useorbits/cli deploy.
Or download an archive from the releases page yourself.
Sign in
$ orbits loginYour browser opens the web app's Sign in the Orbits CLI page, which names the machine asking. Choose:
- Team: the team the CLI acts for. A token acts inside one team.
- Access: Full access (deploy, change settings and domains) or Read only (see projects, deployments and logs).
- Expires: in 30 days, in 90 days, in a year, or never.
Press Approve. The web app creates an API token for the CLI, named after your machine, like CLI-on-mac-mini, and hands it straight to the CLI: it never appears on screen or in a URL. The tab then says you can close it, and the terminal says which team and profile you signed in to.
You need to be an owner or admin of the team, because only they can create API tokens. If the CLI can't open a browser, such as over SSH, orbits login --no-browser prints the link to open on another device instead.
orbits whoami shows who and which team the CLI acts as, and the token's access: full or read only, and the one project it is limited to, if any.
Where the token is kept
The token goes in your system's keychain: the macOS Keychain, or the Secret Service on Linux. On a machine without one, such as a server, it goes in ~/.config/orbits/credentials.json, readable only by you, and the CLI says so when you sign in. Your profiles (which team each one is signed in to) are in ~/.config/orbits/config.json; the token itself is never in that file.
ORBITS_CONFIG_DIR keeps profiles somewhere else, and ORBITS_NO_KEYRING keeps tokens in credentials.json even where there is a keychain.
Sign out
orbits logout forgets the profile's token on this machine. The token itself keeps working until it expires or you revoke it under Team › Settings › API tokens: a token can't revoke itself. A token in ORBITS_TOKEN is never touched: unset it yourself.
Without a browser
On a server or in 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 (see Scripts and CI).
Link a folder
Commands act on a project. Link a folder to one once, and every command run in it, or below it, uses that project:
$ orbits link # pick a project from the team's list, or make a new one$ orbits link storefront # by slug$ orbits link --create # a new upload project named after the folderThe link is .orbits/project.json (the team's and project's ids), and .orbits is added to .gitignore. --project <slug> (and --team <slug>) choose another project for one command. orbits unlink removes the link.
To make a project without linking, use orbits projects create: an upload project by default, or --repo owner/name for one built from a GitHub repository (the team's GitHub must be connected in the web app). See Projects and Deploy from Git.
Deploy
$ orbits deploy # this folder$ orbits deploy ./dist # another folderFor an upload project, the folder is zipped and sent, and Orbits builds it like any other deployment. Uploads go straight to production. Left out of the zip:
node_modules,.git,.next,__MACOSX,.DS_Storeand.orbits.env.localand.env.*.local, the filesorbits env pullwrites- the patterns in the folder's
.orbitsignore, which uses.gitignoresyntax
The zip can be up to 100 MiB, and 500 MiB and 20,000 files unpacked. See Upload a folder.
A Git project builds from its repository, so pushing deploys it. From the CLI:
$ orbits deploy --prod # the production branch's newest commit$ orbits deploy --branch feature/checkout # a preview of another branch$ orbits deployments redeploy # build production's deployment againWhile it builds, the CLI shows each step with its time, and the build log under it, on stderr. --no-logs shows the steps only. When the deployment is ready it prints the address on stdout, so url=$(orbits deploy) works. A failed build exits with code 5 and says where it failed. --no-wait returns as soon as the deployment is queued.
Change what production serves
$ orbits deployments list$ orbits deployments promote dpl_123 # rebuild a preview for production$ orbits deployments rollback # back to the production deployment before this one$ orbits deployments cancel dpl_123A rollback points production at an earlier production deployment straight away, with no rebuild. Automatic production deploys then pause until you promote, so the next push doesn't replace it. These commands ask before they change production; see Deployments.
Logs
$ orbits logs # the newest deployment's build log$ orbits logs dpl_123 -f # follow a build until it ends$ orbits logs --runtime --since 24h --level error$ orbits logs --runtime -f --source functions--runtime shows what the running project logs: requests and function output. It takes --since (1h, 24h or 7d), --level (info, warning or error), --source (requests or functions) and --search. See Runtime logs.
Environment variables
$ orbits env ls$ 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 rm OLD_KEY$ orbits env pull- Values are never printed unless you ask (
env ls --show-values,env pull). env addreads the value from stdin when it isn't on the command line: hidden as you type at a terminal, or piped, which keeps it out of your shell's history.- Variables are sensitive by default: write-only, so nobody can read them back, not even
env pull.--plainmakes one readable. --environmenttakesproduction,previewanddevelopment, comma-separated. The default is production and preview.env pullwrites an environment's readable variables (default: development) to.env.local, readable only by you. It names the sensitive ones it had to leave out, and warns if Git doesn't ignore the file.env rmcan be undone for a while withenv restore <KEY>.- Reading values needs a full-access token.
A changed variable takes effect on the next deployment. See Environment variables.
Domains and DNS
$ orbits domains add shop.example.com$ orbits domains add www.example.com --redirect-to example.com$ orbits domains add example.com --dns orbits$ orbits domains verify shop.example.com$ orbits domains ls --allA new domain serves the linked project's production, or a branch's newest preview with --branch, or redirects with --redirect-to. 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 records ls, add and rm manage the records of a domain on Orbits DNS. See Custom domains.
Everything else
| Command | What it does |
|---|---|
orbits projects list, get, create, delete, pause, resume | Projects |
orbits flags ls, get, create, set, rm, rules add, rules rm | Feature flags per environment |
orbits workflows ls, runs, run, cancel, retry | Workflows and their runs |
orbits alerts ls, create, enable, disable, events, rm | Alerts on error rate, latency and traffic |
orbits usage [--month YYYY-MM] | The team's usage by project |
orbits activity | What happened in the project, or the team with --all |
orbits open [--site] | The project in the web app, or its production site |
orbits teams list, switch | Your signed-in teams |
orbits mcp install, status, list-clients | Connect an AI app to Orbits (below) |
orbits completion <shell>, version, update | Shell completion, the version, a newer version |
The CLI also has orbits sandboxes commands, but sandboxes are not available yet.
orbits <command> --help has the details and examples of each, and the command reference has them all on one page.
AI apps
orbits mcp install <app> adds the Orbits MCP server to an AI app, so it can list, deploy and manage your projects for you. By default it adds the hosted server, https://mcp.theorbits.app/mcp: 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 your machine with your signed-in profile or ORBITS_TOKEN.
The app's config file keeps every other server and setting, and the old file is saved as <file>.bak. --print shows what would be added and changes nothing. orbits mcp list-clients lists the apps it can set up, and orbits mcp status shows which already have Orbits. See Connect your AI app.
Scripts and CI
In CI, set a token in the environment instead of signing in:
$ export ORBITS_TOKEN=orb_live_…$ orbits --project storefront deploy ./dist --no-logsORBITS_TOKENis used instead of any stored sign-in, and nothing is stored. Make it under Team › Settings › API tokens and keep it in your CI's secrets. The CLI acts in the token's team;--teamorORBITS_TEAMname it explicitly.- A read token can only read. Deploying, changing variables and reading their values need full access.
- Results go to stdout; progress and hints go to stderr.
--jsonprints JSON on stdout for every command, and-qprints only ids. Tables, symbols and colour are for terminals: piped output is plain, andNO_COLORturns colour off.- Anything that deletes something or changes production asks first.
--yesanswers for you. Without a terminal and without--yes, the command refuses rather than guess.
Some things no token can do, by design: managing tokens and members, deleting the team, and integrations. The CLI says so and points you to the web app.
Global flags
| Flag | What it does |
|---|---|
--json | Print JSON instead of a table |
-q, --quiet | Print only ids |
-y, --yes | Don't ask before changes that delete something or change production |
--project <slug or id> | The project (default: the folder's linked project) |
--team <slug or id> | The team (default: the linked project's, else the profile's) |
-p, --profile <name> | The profile (default: the current one) |
Environment variables
| Variable | What it does |
|---|---|
ORBITS_TOKEN | The API token to use; skips stored sign-ins |
ORBITS_TEAM | The team, as --team |
ORBITS_PROFILE | The profile, as --profile |
ORBITS_API_URL | The API, with /v1. Default https://api.theorbits.app/v1; staging is https://stagingapi.theorbits.app/v1 |
ORBITS_WEB_URL | The web app used to sign in and by open. Default https://orbits.africa |
ORBITS_CONFIG_DIR | Where profiles live. Default $XDG_CONFIG_HOME/orbits, else ~/.config/orbits |
ORBITS_NO_KEYRING | Keep tokens in credentials.json instead of the system keychain |
ORBITS_NO_UPDATE_NOTIFIER | Don't say when a newer version is out |
Exit codes
| Code | Meaning |
|---|---|
0 | It worked |
1 | An error |
2 | The command was used wrongly |
3 | Not signed in, or the token was refused or may not do this |
4 | Not found |
5 | A build or operation finished, but failed |
130 | Interrupted |
More than one team
A token acts inside one team. To work in several, sign in once per team, each in its own profile, choosing the team in the browser, then switch between them:
$ orbits --profile side-project login$ orbits teams list$ orbits teams switch side-project--profile (or ORBITS_PROFILE) uses another profile for one command or a whole session.
Update and uninstall
$ orbits update # the latest version$ orbits update --check # only print the latest version$ orbits update v0.2.0 # a particular versionorbits update installs the new version in place, checked against the release's checksums first. If you installed with Homebrew, upgrade with brew upgrade orbits instead, and with npm, npm install -g @useorbits/cli@latest; orbits update says which. At most once a day, the CLI says when a newer version is out; ORBITS_NO_UPDATE_NOTIFIER=1 turns that off.
To uninstall, sign out, revoke the CLI's token under Team › Settings › API tokens, then remove the CLI and its settings:
$ orbits logout$ rm -rf ~/.orbits ~/.config/orbitsThen delete the # Orbits CLI lines the installer added to your shell's startup file (~/.zshrc, ~/.bashrc, ~/.bash_profile or fish's config.fish). With Homebrew, run brew uninstall orbits instead of removing ~/.orbits, and with npm, npm uninstall -g @useorbits/cli.