Skip to main content
Every command that manages remote resources sends its request to the active Gateway. The gateway family manages the local profiles that name a Gateway. It also pins the Gateway root certificate authority (CA), installs it in the operating-system trust store, and shows whether the Gateway answers. Gateway trust describes where profiles live, the trust sequence, and the profile guard.

​
Commands

Every command accepts --json. gateway:use and gateway:remove work locally. The other commands contact the Gateway. gateway:add and gateway:trust can change the operating-system trust store, which can ask for local administrator privileges.

​
orbit gateway:add

Add a Gateway profile. The CLI trusts the Gateway root CA first and saves the profile after that. The first profile becomes the active profile.
When the profile name already exists, gateway:add compares the fetched certificate with that profile’s pin, as gateway:trust does. A changed CA fails with gateway.ca_changed unless --accept-ca-change is passed. --ca, when supplied, must also match the fetched certificate. JSON output returns the profile with its url and ca_path, whether it is active, trust_status (trusted or already_trusted), the certificate sha256 fingerprint, and the Gateway request_id.

​
orbit gateway:use

Select an existing profile as the active Gateway. The command changes no pin and no trust store.
An unknown name fails with gateway.profile_not_found. JSON returns active_gateway with the selected name.

​
orbit gateway:status

Show the status and version that the active Gateway reports.
Human output is a detail tree with the profile URL, the Gateway name, status, Orbit version, PHP version, Laravel version, the release it runs from, the automatic release state, and request ID. JSON returns the same values with the profile name and URL. release and release_sha are null outside the release layout. auto_release holds enabled, paused, last_checked_at, and last_result. It is null for a caller that is not an active WireGuard peer, and when the Gateway could not read that state. When this machine is an active WireGuard peer, the Gateway also returns its desired fleet state, as last resolved. It is absent until the Gateway resolves it. Human output then adds CLI release, the version of the Gateway’s CLI release or why it is unavailable, and Agent version, the pinned agent. JSON carries the whole state as desired_fleet_state, which is null for any other caller. self-update installs that state. The command fails with gateway.profile_missing when no profile is active and with gateway.unreachable when the Gateway does not answer. A Gateway response without an error code uses gateway.request_failed; transport failures use gateway.unreachable.

​
orbit gateway:trust

Trust the root CA of the active Gateway in the operating-system trust store, or confirm that it is already trusted.
JSON output returns gateway, status, sha256, ca_path, and request_id. The command uses the error codes of gateway:add, and fails with gateway.profile_missing when no profile is active. Without --accept-ca-change, a Gateway that presents another certificate fails with gateway.ca_changed before anything is installed.
gateway.ca_profile_update_failed means that the certificate is already in the trust store but the profile changed during the command. Check which profile is active and run gateway:trust again.

​
orbit gateway:remove

Remove a profile and delete its pinned certificate file. The operating-system trust store stays unchanged.
The CLI checks the name and the active profile before it asks for consent. The prompt defaults to No. --force allows the removal but does not give consent. A refusal changes nothing. JSON returns profile with the removed name.

​
Gateway releases

The gateway:release commands release the Gateway itself. Update and recover a Gateway describes the release steps, the records, and the error codes. Access to the Gateway is fleet-wide, so any Node with access may run them.

​
orbit gateway:release:list

List the 50 newest release records, newest first, including queued and running ones.
The table shows the record id, the release, the trigger, the outcome, the error code, the duration, and the start time. JSON returns releases with every record field, and request_id.

​
orbit gateway:release:show

Show one release record.
JSON returns the record. gateway.release_not_found means no record matches, and gateway.release_id_invalid means the selector has another form.

​
orbit gateway:release:deploy

Release one commit to the active Gateway, then follow it until it is live, switched back, or paused.
The Gateway queues the release and runs it in its own unit. The CLI reads the record every 2 seconds and shows each step as the Gateway records it: queue, prepare, migrate, switch, hand off, verify, move the scheduler, publish the web app, and smoke. The tree ends with the outcome, and the record id and request ID follow it. JSON prints the final record. The command exits 0 only when the outcome is verified. Interrupting the CLI stops following, not the release. Read the outcome later with gateway:release:show <id>. The CLI keeps reading while the Gateway reloads. It gives up with gateway.release_follow_failed after 30 failed reads in a row, or once 65 minutes have passed, whatever the reads return.

​
orbit gateway:release:rollback

Switch the active Gateway back to a retained release, then follow it.
The Gateway checks that the target is a retained release before it queues anything. Rollback switches code and leaves the database in place. Confirm with --yes for noninteractive or JSON calls; the interactive prompt defaults to No. Declining fails with input.cancelled, and nothing is queued. Database restore is an explicit operator step described in Gateway recovery. Output and exit status follow gateway:release:deploy.

​
orbit gateway:release:smoke

Run the smoke tests of the current release against the live Gateway. Smoke changes nothing and writes no release record.
The Gateway runs bin/gateway-smoke of the current release inside the request and answers when smoke ends, after about a minute by default. Meanwhile the CLI shows one running step. The detail tree shows the commit, the outcome, the check counts, the duration, and the start time. A failed run adds the smoke message and the next step. A table lists each check with its status, error, message, and duration. JSON returns release, sha, outcome, the smoke report, and request_id. The command exits 0 only when the outcome is passed. Interrupting the CLI stops waiting, not smoke. Smoke ends on the Gateway within its own limit.

​
orbit gateway:release:auto:status

Show the automatic release state.
The detail tree shows whether automatic releases are enabled and paused, with the reason of a pause, the current release and commit, the branch and check, the last check and its result, the stalls, and whether the current release’s scheduler has run tasks:tick (post-release tick confirmation). JSON returns enabled, paused, pause, current_release, current_sha, last_tick, stalled_since, branch_head, behind_since, branch, check, tick_confirmation, and request_id.

​
orbit gateway:release:auto:enable and disable

Turn automatic releases on or off.
Both print the resulting state like gateway:release:auto:status. Enabling does not clear a pause. Disabling lets a release that already runs finish.

​
orbit gateway:release:auto:resume

Clear a pause after you decided how to recover from a failed release.
It prints the resulting state. It fails with gateway.release_not_paused when automatic releases are not paused.
  • extension describes the Gateway-owned switches and how unavailable state differs from a disabled extension.
  • node registers the machines that the active Gateway manages.
  • activity lists the requests that the active Gateway recorded.