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

# Installation

> Install the orca CLI on macOS, Linux, or Windows, pin a version, keep it updated, and remove it.

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

The CLI ships as a standalone binary compiled with Bun. There is nothing else to install: no Node.js, no package manager, no runtime dependencies.

## macOS and Linux

```bash theme={"dark"}
curl -fsSL https://orcapods.ai/install.sh | sh
```

The installer:

1. Detects your OS and architecture (`darwin` or `linux`, `arm64` or `x64`).
2. Downloads `orca-<os>-<arch>.tar.gz` from the latest [GitHub release](https://github.com/okikorg/orca-cli/releases).
3. Verifies the archive against the release's `SHA256SUMS` manifest and refuses to install on a mismatch.
4. Installs the binary to `~/.local/bin/orca` and, on macOS, clears the Gatekeeper quarantine attribute so the first run is not blocked.
5. Tells you if `~/.local/bin` is not on your `PATH`, with the exact line to add to your shell profile.

The script needs `curl` or `wget`, `tar`, and either `sha256sum` or `shasum`. If no checksum tool is present the install proceeds without verification and says so.

| Variable           | Effect                                                                    |
| ------------------ | ------------------------------------------------------------------------- |
| `ORCA_VERSION`     | Pin a release tag, for example `ORCA_VERSION=cli-v0.5.0`. Default: latest |
| `ORCA_INSTALL_DIR` | Install somewhere other than `~/.local/bin`                               |

```bash theme={"dark"}
ORCA_VERSION=cli-v0.5.0 ORCA_INSTALL_DIR=/usr/local/bin \
  curl -fsSL https://orcapods.ai/install.sh | sh
```

Verify the install:

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

## Windows

Download `orca-windows-x64.tar.gz` from the [releases page](https://github.com/okikorg/orca-cli/releases), extract it, and place `orca-windows-x64.exe` on your `PATH` (renaming it to `orca.exe` is fine). Self-update is not available on Windows because a running executable cannot replace itself; download a new archive to upgrade.

## From source

If you want to run the CLI from a checkout, for example to try an unreleased change:

```bash theme={"dark"}
git clone https://github.com/okikorg/orca-cli
cd orca-cli
npm install
npm run dev -- --help        # run directly with tsx
npm run build && npm link    # or build and link a global `orca`
```

Node.js 22 or later is required for a source checkout. A source build reports its version from `package.json` and cannot self-update; use `git pull` instead.

<Note>
  The npm package name `@agent-orc/cli` appears in the source tree, but the package is not published to the npm registry. Use the installer or a source checkout.
</Note>

## Updating

The standalone binary updates itself:

```bash theme={"dark"}
orca update            # install the latest release
orca update --check    # only report whether a newer version exists
orca update --tag 0.4.0
```

`orca update` downloads the release archive, verifies it against `SHA256SUMS`, and swaps it over the running binary atomically. See the [orca update reference](/cli/reference/update) for every flag.

`orca --version` also prints a one-line hint on stderr when a newer release exists. That check is cached for 24 hours in `update-check.json` next to the config file, only runs when stderr is a terminal, times out after two seconds, and never blocks the version output. Set `ORCA_NO_UPDATE_CHECK=1` to disable it. If you hit GitHub API rate limits, set `GITHUB_TOKEN` and the check will use it.

## Uninstalling

```bash theme={"dark"}
rm ~/.local/bin/orca            # or wherever ORCA_INSTALL_DIR pointed
rm -rf ~/.config/orca           # stored credentials, contexts, and the update cache
```

Removing the config directory does not revoke the API key stored in it. Run `orca auth logout --revoke` before deleting the directory if you want the key revoked server-side, or revoke it from the dashboard under Settings, then API Keys.