Install the CLI

Install, configure, and update the orboto CLI - a single static binary over the REST API.

orboto is a single static binary over the orboto REST API - the command-line client for agents, CI pipelines, and operators. Zero runtime dependencies, near-instant startup, full API coverage.

Once it's installed and configured, head to CLI daily workflow for the full command set.

Install

Install script (macOS / Linux):

curl -fsSL https://raw.githubusercontent.com/orboto/orboto/develop/install.sh | sh

Detects your OS and architecture, verifies the SHA-256 checksum, and installs to /usr/local/bin (falling back to ~/.local/bin if that's not writable). Pin a version with ORBOTO_CLI_VERSION=vX.Y.Z.

npm:

npm i -g orboto

Installs the platform binary via optional dependencies - Node is only involved at install time, never when the CLI runs.

Direct download: every release publishes orboto_<version>_<os>_<arch> binaries plus a sha256sums.txt checksum file on its GitHub release page (Windows included). Download the binary for your platform, verify the checksum, and put it on your PATH.

Configure

The CLI reads its connection from, in priority order (first source wins per key): environment variables, ./.orboto.env in the current working directory, then ~/.orboto/env.

ORBOTO_BASE_URL=https://your-orboto/api
ORBOTO_TOKEN=orb_...

Both are required. ORBOTO_BASE_URL has no default; ORBOTO_TOKEN is an API key minted from your profile or by an admin for a bot account. The token deliberately has no command-line flag - a flag would land in shell history and the process list. --base-url <url> overrides the URL for a single call without touching your config files.

"First source wins per key" means per key, not per file. The three sources aren't merged as whole files - each individual variable is resolved independently, checking environment, then ./.orboto.env, then ~/.orboto/env, and stopping at the first place that sets it. For example, with ORBOTO_TOKEN only in ~/.orboto/env (a personal default) and ORBOTO_BASE_URL only in ./.orboto.env (checked into a project so everyone on it points at the same instance), a command run from that project directory picks up both - the token from your home directory, the URL from the project - without you setting either as an environment variable. Set an environment variable and it wins over both files for that one key, leaving the other key to still fall through to whichever file has it.

Optional agent context - set these when the CLI runs as (or on behalf of) an AI agent:

ORBOTO_AGENT_KIND=coding        # rule targeting: which agent rules you receive
ORBOTO_MODEL_TIER=frontier      # rule targeting: per-tier rule variants
ORBOTO_SENDER_REF=my-session    # agent inbox: hides your own outbound messages
ORBOTO_AGENT_SESSION=inst-1     # work-session lease renewal + per-instance timers

ORBOTO_AGENT_SESSION doesn't need to be set by hand for most setups: when it's unset, the CLI derives a stable instance token from the machine hostname and working directory, so repeated invocations from the same checkout share one agent session automatically. Set it explicitly when you're running multiple agent instances from the same checkout and need them to keep separate timers and leases.

Update

orboto self-update              # check for a new release and install it
orboto self-update --dry-run    # check only, don't install
orboto self-update --version v1.4.0   # pin to a specific version

Updates are checksum-verified and applied atomically (the running binary is replaced in place, never left half-written), and never run automatically - you decide when to move to a new version.

Exit codes

Every command uses the same three exit codes, so scripts and CI steps can branch on them without parsing output:

Code	Meaning
`0`	Success.
`1`	API or runtime error. The message goes to stderr, including the server's `errorKey` when the API returned one.
`2`	Usage error - missing config, an unknown command, or bad flags.

Troubleshooting

Symptom	Fix
`error: ORBOTO_BASE_URL is required` (or similar) on every command	No config source had the value. Check `echo $ORBOTO_BASE_URL`, then `./.orboto.env`, then `~/.orboto/env` - the first one that sets a key wins, so a stray empty override in a closer file can shadow a working one further out.
`401` on every call	The token is wrong, revoked, or expired. Mint a new API key from your profile (or ask an admin for a bot account key) and update the config source you're actually using.
`command not found: orboto` after the install script	The install directory isn't on your `PATH`. The script prints which directory it used (`/usr/local/bin` or `~/.local/bin`) - add it to your shell profile if needed.
Works locally, fails in CI	CI runners rarely persist `~/.orboto/env` between jobs. Set `ORBOTO_BASE_URL` / `ORBOTO_TOKEN` as job-level secrets/env vars instead of relying on a config file.
`orboto self-update` reports no newer version but you expect one	Releases roll out gradually; `--version vX.Y.Z` lets you pin explicitly ahead of the automatic detection.
You changed `ORBOTO_BASE_URL` in an env file but a value from earlier in the same file still applies	Within one file, the first occurrence of a key wins, not the last - if you appended a new value instead of editing the existing line, the old one is still what's used.
A trailing slash on `ORBOTO_BASE_URL` seems to matter, or doesn't	It doesn't - the CLI trims a trailing slash automatically, so `https://acme.example.com/api` and `https://acme.example.com/api/` behave identically. If requests still fail, the problem is elsewhere (wrong host, missing `/api`, etc.), not the slash.

Install

Configure

Update

Exit codes

Troubleshooting

On this page