> ## 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.

# self-update

> Update this machine to the Gateway's release: the orbit CLI, and orbit-agent on a managed Node.

`self-update` updates this machine to the active Gateway's release. It replaces the `orbit` binary with the CLI release of the Gateway's commit, after a SHA-256 check. On a managed Linux Node it also replaces `orbit-agent` when it differs from the Gateway's pin, and restarts it. [Orbit self-update](/docs/reference/self-update) describes the desired fleet state, each step, and the checks.

## Commands

| Command | Result |
| - | - |
| [`self-update`](#orbit-self-update) | Update the CLI, and the agent on a managed Node. |

The command accepts `--json`.

## orbit self-update

```bash theme={"dark"}
orbit self-update [--allow-downgrade] [--allow-downgrade-to=<version>] [--json]
```

| Option | Default | Meaning |
| - | - | - |
| `--allow-downgrade` | off | Install the Gateway's CLI release even when it is older than this `orbit`, or when this `orbit` is not a release build. |
| `--allow-downgrade-to=<version>` | none | Allow that downgrade only when the Gateway's CLI release is exactly this version, such as `0.4681.0`. The [fleet rollout](/docs/reference/gateway-recovery#one-node) passes it after a Gateway rollback. |

```bash theme={"dark"}
orbit self-update
sudo orbit self-update --json
```

Run it with `sudo` on a Node, and when the binary lives in a directory only root may write, such as `/usr/local/bin`. A source checkout is left alone: update it with `git pull`.

Human output is a progress tree with three steps: read the desired state, update the agent, and update the CLI. Each step shows its result, such as `0.4600.0 → 0.4681.0`, `Already 0.4681.0.`, or why it was skipped.

JSON output is one result:

```json theme={"dark"}
{
  "gateway": "default",
  "commit": "1f0e4c5d6b7a8c9d0e1f2a3b4c5d6e7f8a9b0c1d",
  "outcome": "updated",
  "steps": [
    {
      "step": "agent",
      "outcome": "skipped",
      "reason": "not_managed_node",
      "path": null,
      "before": null,
      "after": null,
      "error": null
    },
    {
      "step": "cli",
      "outcome": "updated",
      "reason": null,
      "path": "/usr/local/bin/orbit",
      "before": {"version": "0.4600.0", "sha256": "ec779baf…"},
      "after": {"version": "0.4681.0", "sha256": "79d7424e…"},
      "error": null
    }
  ],
  "request_id": "0198e15c-bf97-7c23-8f1f-61b8fe67a844"
}
```

| Outcome | Step | Command |
| - | - | - |
| `updated` | The binary was replaced. | A step changed something. Exit 0. |
| `unchanged` | The binary already matches. | Nothing changed. Exit 0. |
| `pending` | The Gateway's CLI release is not published yet. Nothing changed. | Run the command again in a few minutes. Exit 0. |
| `incomplete` | Not a step outcome. | A step that applies here was skipped: the CLI release is unavailable, or the agent needs root. The machine is not up to date. Exit 0. |
| `skipped` | The step did not run; `reason` says why. | Not a top-level outcome. A skip because the step does not apply here, such as `not_managed_node`, leaves the command `unchanged`. |
| `failed` | The step failed; `error` says why. The CLI step does not run after a failed agent step. | Exit 1. |

| Error code | Meaning |
| - | - |
| `self_update.downgrade_refused` | The Gateway's CLI release is older than this `orbit`. Pass `--allow-downgrade` to install it. |
| `self_update.version_unknown` | This `orbit` is not a release build, so it cannot be compared. Pass `--allow-downgrade` to replace it. |
| `self_update.checksum_mismatch` | The download or the release `SHA256SUMS` does not match the Gateway's checksum. Nothing changed. |
| `self_update.candidate_invalid` | The downloaded binary does not start here or reports another version. Nothing changed. |
| `self_update.download_failed` | `curl` could not download an asset. Nothing changed. |
| `self_update.not_writable` | The command may not write to the directory of the binary. Run it with `sudo`. |
| `self_update.install_failed` | The new binary could not be put in place. The old binary is still there. |
| `self_update.release_mismatch` | The Gateway names a download that is not the Orbit release asset this CLI builds. Nothing was downloaded. |
| `agent.checksum_mismatch`, `agent.download_failed`, `agent.install_failed`, `agent.not_writable`, `agent.release_mismatch` | The same failures for `orbit-agent`. Nothing changed. |
| `agent.restart_failed` | `systemctl restart orbit-agent.service` failed for the new agent. The message says whether the previous agent was restored and runs. |
| `agent.unhealthy` | The new agent did not stay active for 5 seconds. The message says whether the previous agent was restored and runs. |

A failure before the steps start, such as `gateway.profile_missing`, `gateway.unreachable`, or `self_update.busy` when another self-update holds the lock for 120 seconds, prints the usual JSON error envelope.

## The newer-release notice

After any other command that reached the Gateway, the CLI prints one line on standard error when the Gateway's fleet runs a newer CLI release, at most once a day:

```text theme={"dark"}
Orbit 0.4681.0 is available (this is 0.4600.0). Run orbit self-update.
```

It appears only when standard error is a terminal and `CI` is unset, and never in JSON output. [The newer-release notice](/docs/reference/self-update#the-newer-release-notice) describes the headers and the throttle.

## Related

* [`gateway`](/docs/cli/gateway) shows the desired fleet state in `gateway:status`.
* [CLI binaries](/docs/reference/cli-binaries) describes the published releases.
* [Node agent](/docs/reference/node-agent#install-and-upgrade) describes the agent pin.


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