Using the CLI

Use orbit to manage fleet records and local client settings. Operational commands use the Gateway API; local Gateway profile, extension, trust, DNS, and HTTP profile commands follow their own documented behavior. The CLI does not open an SSH session to a managed Node. Humans and coding agents use the same commands. Human output is readable in a terminal. A command’s machine mode preserves its documented JSON document or event stream. The API reference documents Gateway operations for clients that call it directly or through the PHP SDK.

Find a command

These entry points show local command information without changing fleet records.

Invocation	Result
`orbit`	Show the command summary.
`orbit --version`	Print the installed version. A released binary prints `Orbit 0.N.0`; a source checkout prints its nearest tag.
`orbit list`	List registered commands.
`orbit help node:show` or `orbit node:show --help`	Show a command’s arguments and options.
`orbit list --format=json`	Print the framework’s command-list JSON format.
`orbit completion zsh`	Print a shell completion script.

Help, command-list formats, version output, and shell completion keep their own formats. They do not gain product JSON envelopes, prompts, or progress output. An unknown command reports the error on standard error and exits with status 1.

Command families

Commands are grouped by the record they manage. Each family has its own page with every command, argument, and option.

Family	Manages
`gateway`	Local Gateway profiles and the trusted root certificate.
`node`	Machines in the fleet, their roles, access grants, and storage settings.
`cluster`	Optional groups of Nodes with one Router and one development TLD.
`firewall`	Named UFW rules on one Node.
`tool`	Packages that Orbit installs on a Node through apt, Composer, Vite+, or Homebrew.
`fleet`	The rollout that brings managed Nodes to each Gateway release, and resuming it after a halt.
`github`	The Gateway’s own GitHub App, its registration, and its installations.
`metrics`	The Prometheus and Grafana role and its exporters.
`analytics`	The Plausible version the analytics role runs.
`dns`	A local development TLD resolver override on the operator machine.
`project`	Project records with one repository and type each.
`instance`	Instances: development checkouts and production releases of a Project on one Node.
`route`	Hostnames that reach an Instance.
`env`	Stored Instance environment configuration and its `.env` projection.
`database`	The registry of mysql, pgsql, sqlite, and redis connections, including MySQL user create and list through a Node Process.
`process`	systemd services and Docker containers owned by an Instance, a Node, or a Project definition.
`schedule`	Recurring commands run by native systemd timers.
`doctor`	Verify-only drift checks across the fleet.
`profile`	One local HTTP request profiler on the operator machine.
`self-update`	Update this machine to the Gateway’s CLI release, and `orbit-agent` on a managed Node.
`activity`	The Gateway’s log of who ran what.
`realtime`	The Gateway’s realtime Reverb connection details and event stream.
`extension`	Optional local command extensions.
`tasks`	Tasks, their subtasks and comments, and the Gateway tasks extension.

Select a Gateway

The CLI stores Gateway profiles in $HOME/.orbit/config.json. Set ORBIT_HOME to move that directory. Commands that require a Gateway use the selected profile.

orbit gateway:add 10.70.0.1 --use
orbit gateway:status

gateway:add fetches the Gateway root certificate, pins it, and installs it in the operating-system trust store. The gateway family and the Gateway trust reference describe the trust sequence and its recovery paths.

Name the record you mean

Use the arguments and selectors documented for the command. A numeric ID, name, slug, UUID, or Route domain is accepted only where that command permits it. In a terminal, a command prompts for a required target or value you omit and offers a default where one exists. With --json or --no-interaction, it refuses the omitted input with its documented error code. When a command permits a prompt, enter a value or select from its admitted choices. Invalid prompted input is checked before the command continues. Cancelling before work begins selects no target and starts no mutation. An interruption after work starts may leave partial work; inspect the reported result before retrying. Use --no-interaction or -n to disable prompts. Supply required values through the command’s arguments and options. For automation, use the command’s documented noninteractive inputs and explicit consent option.

Confirm destructive changes

Read the command’s confirmation and override options before automating a destructive change. An existing consent option and an override can have different effects. For example, discarding dirty source is separate from choosing an output format. Do not assume that --force has the same meaning across families or that selecting JSON authorizes a mutation. The contributor CLI design standard defines the shared consent rules. Each family page documents its supported options and refusal conditions.

Read machine-readable output

Use --json where the command supports it. Preserve its documented shape when writing scripts; a final-response command and a streaming command have different contracts. Framework commands such as list use their own format options. Gateway command failures use a stable error code and request correlation when available:

{
  "error": {
    "code": "route.target_conflict",
    "message": "Instance 12 already belongs to Route 4.",
    "request_id": "9d6b1e5c-4a3f-4a1b-9f0e-6d2c3f5a7b81"
  }
}

Error codes are namespaced by family, such as node.not_active, schedule.calendar_invalid, or env.operation_busy. The reference pages list each family’s codes and what the Gateway leaves in place after a refusal. instance:deploy and instance:rollback stream newline-delimited JSON (NDJSON) instead of one document, because they report phases and application output while the Gateway is still working. The instance family describes that event stream.

Follow a request through the Gateway

Use a Gateway request ID, when the result supplies one, to find the matching Activity. A local or parser failure may have no Gateway request; its error request ID is null.

orbit activity:list --request-id=9d6b1e5c-4a3f-4a1b-9f0e-6d2c3f5a7b81
orbit activity:show 481

Activity records identify the operation, target, caller, and result. They never contain commands, environment values, credentials, or remote output.

Retry after a connection failure

A command that reads from the Gateway retries the read once. When the connection is refused, reset, or closed before any HTTP response, the CLI waits 250 milliseconds and sends the same read again with the same request ID. A Caddy reload on the Gateway can cause these failures. The CLI never retries a change, a read that received any HTTP response (including a 5xx error), a timeout, or a deployment stream. A second failure ends the command with the error. The read and its retry share the 900-second request timeout, so the retry never extends it. A refused or reset connection usually fails within milliseconds, so the retry usually adds about 250 milliseconds.

Exit status

A successful command exits with 0. A handled failure returns the command’s documented nonzero status. Local commands do not need a Gateway request to succeed. Parser usage errors, product refusals, and failed streams keep their existing statuses; scripts should check the exit status as well as the result.

Enable an extension

Some command families are hidden until you enable them at the Gateway. The Gateway state composes the CLI, MCP, API, and web surfaces for every client. extension:enable only reveals a family; proxycli:setup separately deploys its collector. See extension and proxycli.

orbit extension:list
orbit extension:enable proxycli

The extension family lists the available extensions.

Shell completion

The CLI is a Laravel Zero application, so orbit completion bash and orbit completion zsh print a completion script for your shell.

orbit completion zsh > ~/.zfunc/_orbit

Using the CLI

Fleet

Applications

Operations

Using the CLI

Find a command

Command families

Select a Gateway

Name the record you mean

Confirm destructive changes

Read machine-readable output

Follow a request through the Gateway

Retry after a connection failure

Exit status

Enable an extension

Shell completion

​Find a command

​Command families

​Select a Gateway

​Name the record you mean

​Confirm destructive changes

​Read machine-readable output

​Follow a request through the Gateway

​Retry after a connection failure

​Exit status

​Enable an extension

​Shell completion

Find a command

Command families

Select a Gateway

Name the record you mean

Confirm destructive changes

Read machine-readable output

Follow a request through the Gateway

Retry after a connection failure

Exit status

Enable an extension

Shell completion