CLI reference

text

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

orbit init [--recipe NAME] [--force] [--list]

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

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

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

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: pass both host and slot, or neither.

Neither reads the mapping for the current Git branch from ~/.config/orbit/config.json ($XDG_CONFIG_HOME/orbit/config.json when set). The repository key is the origin remote URL when configured; otherwise the absolute path to the repo root. Detached HEAD has no mapping — pass the target explicitly.

status also accepts host only:

bash

orbit status ship    # slots with src/ on the host

Host values

Passed to OpenSSH unchanged:

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          default SSH user

Must not start with - or contain /.

`setup`

bash

orbit setup ship --email you@example.com

Prepares Ubuntu host layout, permissions, system Caddy, and TTL timers. Interactive SSH (sudo prompts). See Prepare the host.

`init`

bash

orbit init

orbit init --list

orbit init --recipe stario-podman

orbit init --force

Writes ops/ in the current Git repository. Auto mode runs each bundled recipe's recognizer and uses the first match: stario-podman, python-podman, then static-caddy. Recognition failure means that recipe does not handle this tree. --recipe writes that recipe even when recognition fails. --force replaces existing hook files. Edit the written scripts; later deploys do not rewrite them.

`create`

bash

orbit create ship app.example.com

Creates slot directories. Successful create writes the local target mapping.

Generated preview name:

bash

orbit create ship {}.example.com

# created ship calm-otter.example.com

With expiry (max 30d; 30m, 6h, 2d, …):

bash

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

Expiry permanently purges the slot. An explicit slot name can reuse retained data and env after a normal remove.

`deploy`

bash

orbit deploy ship app.example.com

Mirrors the Git work tree into $SLOT_SRC, runs ops/deploy (must exist). Orbit runs it with bash. Requires a clean work tree so the upload matches HEAD. --force also uploads local modifications and non-ignored untracked files.

bash

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

orbit deploy --force

orbit deploy    # after a saved mapping exists

`status`

bash

orbit status ship app.example.com

orbit status                    # saved mapping

orbit status ship               # slots with src/ on the host

Runs ops/status when present. Without a hook, prints unknown and exits 0. With no src/ directory, prints missing and exits 1.

`env`

bash

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

orbit env ship app.example.com --set APP_ENV=production --set LOG_LEVEL=info

orbit env ship app.example.com --edit

Print keys (values redacted) when no action is given. Stored at $SLOT_ENV, mode 0600.

`remove`

bash

orbit remove ship app.example.com

orbit remove ship app.example.com --purge

orbit remove ship app.example.com --yes

Runs ops/remove when present, then removes src and run. Keeps data and env unless --purge. Manual remove cancels an active expiry timer.

User config

json

  "version": 1,

  "remotes": {

    "github.com/acme/app": {

      "branches": {

        "main": {

          "host": "ship",

          "slot": "app.example.com"

Successful create and deploy create or update the entry. Preview TTL stores expires_at; Orbit prunes expired entries on read.