Install the CLI

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-cli/main/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

Run orboto login. It asks for the workspace address (https://acme.orboto.example is enough, the CLI appends /api), opens your browser for the orboto login and saves the result; orboto whoami then answers with your identity.

orboto login --api-key                 # paste an orb_ key instead (hidden input; piped stdin for scripts)
orboto login --no-browser              # print the login address instead of opening a browser (SSH boxes)
orboto login --profile work            # save as a named connection profile (browser or key)
orboto logout [--profile work]         # forget it; a browser login is revoked server-side

An API key lands in ~/.orboto/env, a browser login in ~/.orboto/oauth.json (renewed automatically), a profile in ~/.orboto/profiles/<name>.json. Any command that finds no configuration while a terminal is attached runs the same setup and continues; scripts get the error plus the hint (ORBOTO_NO_INTERACTIVE=1 forces that). The manual sources below still work and take precedence.

For separate accounts or servers, use connection profiles with CLI 0.180.0 or later. Each profile holds one complete server/key pair; --profile or the per-process ORBOTO_PROFILE selector chooses it explicitly. There is no shared active-account switch.

Without a selected profile, legacy configuration works as follows.

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 (a local project configuration), 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.

Added in v0.211.3 A token only goes to the server it was saved with. A server address from ./.orboto.env is used only with a token from the same file (or a token whose own file names the same address). A token from a file that names a server is never sent to another address, not even one from --base-url or ORBOTO_BASE_URL in the environment; the command fails with exit code 2 and a message that names the fix: run orboto login for that server, put both keys in one file, or set both in the environment. orboto login writes both keys into ~/.orboto/env. A token from the process environment, or from a file that names no address, is not bound. Two names for one server (localhost and 127.0.0.1, or a LAN name and a public name) count as two servers. Only the connection keys (ORBOTO_BASE_URL, ORBOTO_TOKEN, ORBOTO_AGENT_KIND, ORBOTO_MODEL_TIER, ORBOTO_SENDER_REF) are read from these files; every other line is ignored.

Keep .orboto.env out of version control. Because legacy sources resolve independently, check both the destination and returned identity before work. Use a complete connection profile to avoid mixing a server and key.

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. Added in v0.230.0 A launcher (orboto claude, orboto kimi, orboto agy and the others) needs no such variable: a second launcher in a checkout whose token another launcher already uses takes a token of its own (-s2, -s3), see Session origin and state.

Update

Binaries older than 0.179.0 need a one-time reinstall. Their release lookup targets an obsolete repository and can return 404. Run the public install script above or npm i -g orboto, then verify orboto version. Subsequent updates can use self-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.

Command names

Commands follow one scheme, a noun and then a verb: orboto ticket list ACME, orboto ticket claim ACME-42, orboto project list, orboto milestone create ACME "Sprint 5", orboto timer start ACME-42, orboto doc get ACME-D12. This applies to the orboto binary and the Node skill wrapper alike. orboto ticket <KEY> stays the short form of orboto ticket get <KEY>. In the skill wrapper, ticket deps, ticket set-parent and ticket duplicate-report are not available; they exist in the native CLI only.

Nothing breaks: every earlier name keeps working, so scripts need no change.

In an interactive terminal, an old name prints one line on stderr that names the new command, for example: orboto: claim is now ticket claim (the old name keeps working).

The line never appears when stderr is not a terminal (scripts, pipes, agents), with --json or --help, or with ORBOTO_NO_ALIAS_HINT=1.

orboto help ticket list shows the aliases of a command.

Exit codes

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

With CLI 0.180.0 or later, help, --help, -h and command help such as orboto ticket create --help print to stdout and exit 0, even without credentials. They do not contact the server, check updates, consume stdin or perform the requested operation. version, --version and -v also print to stdout and exit 0.

Command options may precede or follow positional arguments. Use -- to end option parsing when content begins with a dash:

orboto ticket comment ACME-42 -- --help is the text of this comment

A value consumed by an option remains content: --description --help sets a literal description instead of requesting help. Arguments after pi-runner -- belong to the child process.

work-next additionally exits 3 when no work is ready; see work routing.

• orboto project change-key without --confirm-project-key prints the dry run and exits 1; --dry-run exits 0.

Troubleshooting