orbital CLI

orbital is the official command-line tool for OrbitalReg. A single static binary, no runtime dependencies, ~12 MB. Source under tools/cli/.

The full subcommand reference is generated directly from the binary via orbital docs --out-dir docs-site/reference/cli/ and committed under reference/cli/ at every release tag — see Generating offline docs below to render your own copy without internet access.

The migration suite carries its own hand-curated reference at reference/cli/migrate — flag tables, exit codes, and end-to-end recipes for plan / apply / verify / finalize.

Install

macOS / Linux (Homebrew)

brew tap orbitalreg/tap
brew install orbital
orbital --version

The Homebrew formula installs shell completions for bash, zsh, and fish automatically. Restart your shell to pick them up.

Windows (Scoop)

scoop bucket add orbitalreg https://github.com/orbitalreg/scoop-bucket
scoop install orbital
orbital --version

Direct download

Tagged releases are published at https://github.com/orbitalreg/orbitalreg/releases/tag/cli/v<X.Y.Z> with the following assets:

Asset	Contents
orbital_<version>_<os>_<arch>.tar.gz	binary + completions for bash/zsh/fish/PowerShell
orbital_<version>_windows_amd64.zip	same, zipped for Windows
orbital_<version>_SHA256SUMS	SHA-256 manifest of every asset
orbital_<version>_SHA256SUMS.sig	cosign keyless signature on the manifest

Verifying a release

Releases are signed with cosign keyless via the GitHub Actions OIDC issuer — no long-lived signing key. Verify the SHA256SUMS file before extracting binaries:

TAG=cli/v0.1.0
curl -LO "https://github.com/orbitalreg/orbitalreg/releases/download/${TAG}/orbital_$(echo ${TAG#cli/v})_SHA256SUMS"
curl -LO "https://github.com/orbitalreg/orbitalreg/releases/download/${TAG}/orbital_$(echo ${TAG#cli/v})_SHA256SUMS.sig"

cosign verify-blob \
  --certificate-identity-regexp "https://github.com/orbitalreg/orbitalreg/.github/workflows/cli-release.yml@refs/tags/cli/v.*" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
  --signature orbital_<version>_SHA256SUMS.sig \
  orbital_<version>_SHA256SUMS

Then extract the per-platform tarball and run sha256sum -c orbital_<version>_SHA256SUMS against it.

Generating offline docs

Customers running an air-gapped deployment can render the full subcommand reference from their installed binary, with no internet required:

orbital docs --out-dir ./cli-docs/             # Markdown (default)
orbital docs --out-dir ./cli-man/  --format man # man-pages
orbital docs --out-dir ./cli-rst/  --format rest # Sphinx ReST

Each Markdown file carries title + version YAML front-matter so a docs-site (VitePress, MkDocs, Hugo) can ingest the tree without post-processing.

Shell completion

# Bash (Linux, system-wide)
orbital completion bash | sudo tee /etc/bash_completion.d/orbital >/dev/null

# Zsh
orbital completion zsh > "${fpath[1]}/_orbital"

# Fish
orbital completion fish > ~/.config/fish/completions/orbital.fish

# PowerShell (current session)
orbital completion powershell | Out-String | Invoke-Expression

Add the matching line to your shell's startup file to persist completions across sessions.

Configuration

orbital looks for its config file at $XDG_CONFIG_HOME/orbital/config.yaml (~/.config/orbital/config.yaml on Linux/macOS by default). Multi-profile is supported via the top-level default_profile key plus a profiles: map; the active profile is selected via --profile <name> or ORBITAL_PROFILE=<name>.

Every persistent flag has an env-var override:

Flag	Env var	Default
--config	ORBITAL_CONFIG	~/.config/orbital/config.yaml
--profile	ORBITAL_PROFILE	default
--endpoint	ORBITAL_ENDPOINT	(profile)
--token	ORBITAL_TOKEN	(profile)
--output	ORBITAL_OUTPUT	table

CI scripting

Every subcommand supports --output json. Errors surface on stderr; data is on stdout. Exit codes are deterministic — branch on $? rather than parsing log lines:

Code	Meaning
0	success
1	user error (bad flags, missing args, parse error, 4xx data)
2	auth error (401, 403, no token configured)
3	server error (5xx, transport failure, malformed response)
4	other / unclassified

if ! orbital --output json auth status >/tmp/who.json; then
  case $? in
    2) echo "auth required"; exit 1;;
    3) echo "OrbitalReg server unreachable"; exit 1;;
    *) echo "unexpected error"; exit 1;;
  esac
fi