Skip to main content
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; only --json changes its behavior.

​
orca update

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

​
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); 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

​
orca help

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.

​
orca —version

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.
Verified against orca-cli cli-v0.5.0.