OrbitsDocs
esc
    Open Orbits
    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.

    Terminal
    $ 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.app

    Install

    Terminal
    $ curl -fsSL https://orbits.africa/install | bash

    The 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:

    Terminal
    $ orbits --version
    • To install a particular version, pass it to the script: curl -fsSL https://orbits.africa/install | bash -s -- v0.1.0.
    • ORBITS_INSTALL installs somewhere other than ~/.orbits.
    • ORBITS_NO_MODIFY_PATH=1 leaves your shell's startup file alone.

    With Homebrew instead:

    Terminal
    $ brew install The-Orbits/tap/orbits

    With npm, or pnpm, Yarn or Bun (Node.js 18 or later):

    Terminal
    $ npm install -g @useorbits/cli

    The 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

    Terminal
    $ orbits login

    Your 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:

    Terminal
    $ orbits login --with-token < token.txt

    Or store nothing and set ORBITS_TOKEN (see Scripts and CI).

    Commands act on a project. Link a folder to one once, and every command run in it, or below it, uses that project:

    Terminal
    $ 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 folder

    The 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

    Terminal
    $ orbits deploy            # this folder$ orbits deploy ./dist     # another folder

    For 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_Store and .orbits
    • .env.local and .env.*.local, the files orbits env pull writes
    • the patterns in the folder's .orbitsignore, which uses .gitignore syntax

    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:

    Terminal
    $ 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 again

    While 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

    Terminal
    $ 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_123

    A 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

    Terminal
    $ 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

    Terminal
    $ 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 add reads 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. --plain makes one readable.
    • --environment takes production, preview and development, comma-separated. The default is production and preview.
    • env pull writes 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 rm can be undone for a while with env restore <KEY>.
    • Reading values needs a full-access token.

    A changed variable takes effect on the next deployment. See Environment variables.

    Domains and DNS

    Terminal
    $ 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 --all

    A 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

    CommandWhat it does
    orbits projects list, get, create, delete, pause, resumeProjects
    orbits flags ls, get, create, set, rm, rules add, rules rmFeature flags per environment
    orbits workflows ls, runs, run, cancel, retryWorkflows and their runs
    orbits alerts ls, create, enable, disable, events, rmAlerts on error rate, latency and traffic
    orbits usage [--month YYYY-MM]The team's usage by project
    orbits activityWhat 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, switchYour signed-in teams
    orbits mcp install, status, list-clientsConnect an AI app to Orbits (below)
    orbits completion <shell>, version, updateShell 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:

    Terminal
    $ export ORBITS_TOKEN=orb_live_…$ orbits --project storefront deploy ./dist --no-logs
    • ORBITS_TOKEN is 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; --team or ORBITS_TEAM name 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.
    • --json prints JSON on stdout for every command, and -q prints only ids. Tables, symbols and colour are for terminals: piped output is plain, and NO_COLOR turns colour off.
    • Anything that deletes something or changes production asks first. --yes answers 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

    FlagWhat it does
    --jsonPrint JSON instead of a table
    -q, --quietPrint only ids
    -y, --yesDon'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

    VariableWhat it does
    ORBITS_TOKENThe API token to use; skips stored sign-ins
    ORBITS_TEAMThe team, as --team
    ORBITS_PROFILEThe profile, as --profile
    ORBITS_API_URLThe API, with /v1. Default https://api.theorbits.app/v1; staging is https://stagingapi.theorbits.app/v1
    ORBITS_WEB_URLThe web app used to sign in and by open. Default https://orbits.africa
    ORBITS_CONFIG_DIRWhere profiles live. Default $XDG_CONFIG_HOME/orbits, else ~/.config/orbits
    ORBITS_NO_KEYRINGKeep tokens in credentials.json instead of the system keychain
    ORBITS_NO_UPDATE_NOTIFIERDon't say when a newer version is out

    Exit codes

    CodeMeaning
    0It worked
    1An error
    2The command was used wrongly
    3Not signed in, or the token was refused or may not do this
    4Not found
    5A build or operation finished, but failed
    130Interrupted

    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:

    Terminal
    $ 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

    Terminal
    $ orbits update            # the latest version$ orbits update --check    # only print the latest version$ orbits update v0.2.0     # a particular version

    orbits 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:

    Terminal
    $ orbits logout$ rm -rf ~/.orbits ~/.config/orbits

    Then 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.

    Was this page helpful?

    Updated