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

# orca update

> Check for and install a newer orca CLI release, plus the help and version commands.

> **Last updated: 2026-09-06**

`orca update` upgrades the standalone `orca` binary in place from the project's GitHub Releases. Releases are tagged `cli-v<semver>` and ship one `orca-<os>-<arch>.tar.gz` per platform alongside a `SHA256SUMS` manifest.

The command accepts the [global flags](/cli/reference/overview#global-flags); only `--json` changes its behavior.

## orca update

```bash theme={"dark"}
orca update [--check] [--force] [--tag <version>]
```

Resolves the target release (the latest, or the one named by `--tag`), compares it with the running version, and installs it when it is newer. The release is read from the GitHub API at `api.github.com/repos/okikorg/orca-cli/releases/latest` (or `/releases/tags/<tag>`) with a 10 second timeout; a failed lookup exits 1 with a link to the releases page.

| Flag              | Type    | Default        | Description                                                            |
| ----------------- | ------- | -------------- | ---------------------------------------------------------------------- |
| `--check`         | boolean | `false`        | Report whether a newer version exists, but do not install it           |
| `--force`         | boolean | `false`        | Reinstall the target version even if it matches the current one        |
| `--tag <version>` | string  | latest release | Install a specific version. Accepts `cli-v0.1.0`, `v0.1.0`, or `0.1.0` |

Self-update only works for the standalone binary (the one installed by the install script), because only a Bun-compiled binary carries an injected version and can rewrite its own executable. When the running `orca` is not standalone (a source checkout), the command prints guidance instead of updating: `git pull` in the checkout, or re-run the install script to switch to the standalone binary. See [Installation](/cli/installation). On Windows the command refuses, since a running `.exe` cannot replace itself; download `orca-windows-x64.tar.gz` from the releases page instead. Both refusals exit 0.

An update proceeds in four steps, each reported on stderr in a terminal:

1. Download the asset for the current platform and architecture (`darwin` or `linux`, `arm64` or `x64`) into a staging directory named `.orca-update-<pid>` next to the running executable.
2. Fetch `SHA256SUMS` from the same release and verify the tarball's SHA-256 digest against it. A missing entry or a mismatch aborts the update.
3. Extract the single `orca` executable with `tar` (which must be on `PATH`) and copy the current binary's file mode onto it.
4. Rename it over the running executable. The staging directory is on the same filesystem, so the swap is atomic and works while the old binary is still running. The staging directory is removed afterwards.

A permission error writing to the install directory exits 1 with a hint to re-run with elevated permissions or reinstall.

```bash theme={"dark"}
orca update --check
orca update
orca update --tag 0.5.0 --force
```

With `--json` every path prints one object. `--check` prints `current`, `currentTag`, `latest`, `latestTag`, `updateAvailable`, and `htmlUrl`. The other paths print the same fields plus `updated` (`true` or `false`); a refusal adds `reason` (`windows` or `not-standalone`), and a successful install adds `path`.

```json theme={"dark"}
{
  "current": "0.4.0",
  "currentTag": "cli-v0.4.0",
  "latest": "0.5.0",
  "latestTag": "cli-v0.5.0",
  "updateAvailable": true,
  "htmlUrl": "https://github.com/okikorg/orca-cli/releases/tag/cli-v0.5.0",
  "updated": true,
  "path": "/usr/local/bin/orca"
}
```

### Update check on `orca --version`

Printing the version (`orca -v` or `orca --version`) also runs a best-effort update check and, when a newer release exists, prints `A newer version (cli-vX.Y.Z) is available. Run: orca update` on stderr. The result is cached for 24 hours in `update-check.json` under the config directory (see the [config file location rules](/cli/reference/auth-and-context#config-file)); a live check uses a 2 second timeout and falls back to the stale cache when it fails. The check is skipped entirely when `ORCA_NO_UPDATE_CHECK` is set or stderr is not a TTY, and it never blocks or changes the version output. `orca update` itself does not use the cache.

### Environment

| Variable                     | Effect                                                                                       |
| ---------------------------- | -------------------------------------------------------------------------------------------- |
| `ORCA_NO_UPDATE_CHECK`       | When set to any value, disables the update hint on `orca --version`                          |
| `GITHUB_TOKEN` or `GH_TOKEN` | Sent as a bearer token on GitHub API requests to lift the low anonymous rate limit; optional |

## orca help

```bash theme={"dark"}
orca help [command]
```

Prints the top-level help, or the help for one command. The top-level help is grouped into `CORE`, `OBSERVE`, `MANAGE`, and `SETUP` sections and, on a machine that has never signed in (no config file and no `ORCA_API_KEY`), notes that `orca auth login` is the first command to run. Running bare `orca` with no arguments prints the same top-level help. `orca <command> --help` is equivalent for a single command. Exit code 0.

```bash theme={"dark"}
orca help runs
```

## orca --version

```bash theme={"dark"}
orca --version
orca -v
```

Prints the bare semver of the running CLI (for example `0.5.0`) on stdout, followed by the update hint described above when one applies. Exit code 0.

<Note>
  Verified against orca-cli `cli-v0.5.0`.
</Note>