CLI reference

Orbit commands act on a remote host and a named slot.

text

orbit setup <host> [--email you@example.com]

orbit create [<host> <slot>] [--ttl 6h]

orbit create <host> {}.example.com [--ttl 6h]

orbit deploy [<host> <slot>] [--dry-run]

orbit status [<host> [<slot>]]

orbit env [<host> <slot>] [--set KEY=VALUE | --from FILE | --edit]

orbit remove [<host> <slot>] [--purge] [--yes]

Target arguments

For create, deploy, env, and remove, provide both host and slot, or provide neither.

When both values are omitted, Orbit reads the target saved for the current Git remote and branch. A detached HEAD has no branch mapping, so pass the target explicitly.

status also accepts only a host:

bash

orbit status ship

This lists all slots on that host.

Host values

Orbit passes the host value to OpenSSH. Accepted forms include:

text

ship                      Host alias in ~/.ssh/config

deploy@host.example.com   user and hostname

deploy@203.0.113.10       user and address

host.example.com          hostname with the default SSH user

The value must not start with - or contain /.

`setup`

bash

orbit setup ship --email you@example.com

Prepares the Ubuntu host, slot tree, permissions, Caddy service, and optional expiry support. If --email is omitted, Orbit prompts for the ACME email.

Setup uses an interactive SSH session because sudo can prompt. Normal Orbit commands use SSH batch mode.

Setup changes the system Caddy service. Read Prepare the host before you run it.

`create`

bash

orbit create ship app.example.com

Creates an empty slot. A successful create saves the target for the current Git remote and branch.

Use one {} placeholder for a generated preview name:

bash

orbit create ship {}.example.com

# created ship calm-otter.example.com

Generated names do not reuse a slot tree that still contains retained data, environment values, or runtime files. An explicit slot name can reuse retained data and env after a normal removal.

Add an expiry:

bash

orbit create ship {}.example.com --ttl 6h

Durations use minutes, hours, or days, such as 30m, 6h, or 2d. The maximum is 30d. Expiry permanently purges the slot.

`deploy`

bash

orbit deploy ship app.example.com

Selects the current Git work tree, mirrors it into the slot source, and runs ops/deploy.sh. The script must exist and be executable.

Orbit reports the local HEAD revision, streams hook output, and returns the hook exit status. A dirty work tree is allowed and is included in the upload.

Preview target resolution without changing the remote host:

bash

orbit deploy ship app.example.com --dry-run

After Orbit has saved a target for the current remote and branch, use:

bash

orbit deploy

`status`

Show one slot:

bash

orbit status ship app.example.com

Show the saved slot for the current Git remote and branch:

bash

orbit status

Show all slots on a host:

bash

orbit status ship

Orbit runs ops/status.sh when it exists. A missing hook reports unknown.

`env`

Replace the complete slot environment from a local file:

bash

orbit env ship app.example.com --from .env.production

Set one or more values while keeping the other values:

bash

orbit env ship app.example.com \

  --set APP_ENV=production \

  --set LOG_LEVEL=info

Edit the environment with the configured terminal editor:

bash

orbit env ship app.example.com --edit

Without an action, Orbit prints sorted keys and redacts the values:

text

APP_ENV=<redacted>

DATABASE_URL=<redacted>

The environment is stored at $SLOT_ENV with mode 0600. Orbit transfers the complete file to the local process when it reads or edits values. Anyone who can connect as the deploy user can read it.

`remove`

Stop and remove a slot:

bash

orbit remove ship app.example.com

Orbit runs ops/down.sh when present, then removes synchronized source and runtime files. It keeps durable data and environment values so an explicit create of the same slot can reuse them.

Permanently delete the complete slot:

bash

orbit remove ship app.example.com --purge

Use --yes to skip the confirmation prompt.

Manual removal cancels an active expiry timer. An expiry is always a purge.

User config

Orbit stores local target mappings at:

text

~/.config/orbit/config.json

If $XDG_CONFIG_HOME is set, Orbit uses $XDG_CONFIG_HOME/orbit/config.json.

Mappings use a normalized origin remote URL and branch:

json

  "version": 1,

  "remotes": {

    "github.com/acme/app": {

      "branches": {

        "main": {

          "host": "ship",

          "slot": "app.example.com"

Successful create and deploy commands create or update the mapping.