> ## Documentation Index
> Fetch the complete documentation index at: https://orbit.nckrtl.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Using the CLI

> How the orbit command line talks to the Gateway, selects records, confirms destructive changes, and returns machine-readable output.

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

```bash theme={"dark"}
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](/docs/cli/gateway) and the [Gateway trust reference](/docs/reference/gateway-trust) 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](/docs/reference/cli-ux#consent) 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:

```json theme={"dark"}
{
  "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](/docs/cli/instance#orbit-instancedeploy) 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`.

```bash theme={"dark"}
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](/docs/cli/extension) and [proxycli](/docs/cli/proxycli).

```bash theme={"dark"}
orbit extension:list
orbit extension:enable proxycli
```

The [extension family](/docs/cli/extension) 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.

```bash theme={"dark"}
orbit completion zsh > ~/.zfunc/_orbit
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.