Skip to content
arbe docs
View as .md

CLI

For sandbox/environment/secret commands, see runtime.

arbe — agent harness, task tracker, build loop. See architecture for how it’s wired.

The core loop: arbe task ready → arbe task claim <id> → implement → arbe task close <id>. Interactive work via arbe chat, one-off sandbox commands via arbe x.

Install

Terminal window
curl -fsSL https://arbe.0sk.ar/install.sh | sh   # → ~/.local/bin/arbe
arbe auth login                                  # browser OAuth, stores token
arbe status                                      # account + sandboxes + ready tasks
arbe chat "hello"                                # exercise the agent path

The script picks darwin-arm64 / darwin-x64 / linux-x64 from uname, downloads arbe-$TARGET.tar.gz + SHA256SUMS from https://downloads.arbe.0sk.ar/arbe/latest/, verifies the sha256, and drops the binary in $ARBE_INSTALL_DIR (default ~/.local/bin). latest/ is mutable — fetch tarball and SHA256SUMS together so they describe the same build. Linux ARM is not built. To pin a version, see releases.

Manual install: curl -fLO https://downloads.arbe.0sk.ar/arbe/latest/arbe-$TARGET.tar.gz + same for SHA256SUMS → grep "arbe-$TARGET.tar.gz" SHA256SUMS | sha256sum -c - (or shasum -a 256 -c - on macOS) → tar -xzf … → move arbe onto your $PATH. If the checksum fails, do not run the binary — re-download both files together.

  • arbe --version reports the baked-in version, commit SHA, and build date — paste that into bug reports because latest itself moves.
  • arbe auth login is mandatory for anything that creates a thread (chat, thread create); for CI, arbe auth login --token <value>. arbe auth whoami confirms which agent and house the token resolves to; arbe auth logout drops both.
  • No anonymous fallbacks — every thread belongs to a house, and every house has an owner.

Updating: arbe upgrade self-installs over a released binary (--check to inspect without installing); the CLI also does a passive best-effort check on interactive runs. On a bun link source checkout the updater refuses — refresh your checkout instead. Install script source: apps/www/static/install.sh.

Commands

setup-claude            install the arbe, librarian, and oracle agents for Claude Code
auth                    authenticate and manage session


task (t)                create, list, update tasks
chat (c)                launch local pi chat, interactive by default or one-shot with a message
status                  quick-glance overview — auth, sandboxes, ready tasks
gif                     search GIFs and print result URLs


house (h)               show or switch the active house
thread                  threads — the canonical conversation primitive (entries live underneath)
env                     list and inspect environments in a house
files                   add, list, and search files in a house


agent (a)               list and manage agents
team                    install and manage teams (agent + thread bundles)
member                  list and manage house members
invite                  manage invite links for houses
sandbox                 manage sandboxes (list, create, destroy, setup, view, diagnose)
x                       run a command in a sandbox (daytona by default; raw argv — use -- bash -lc for pipes)
secret                  manage secrets for a house
config                  read and write per-scope configuration


loop (l)                loop local agent n times (default 5)
upgrade                 check for updates and install if available
debug (d)               wire-level debugging tools and raw API access
http                    authenticated request to www API (uses arbe auth login token)
skills                  list or print skills
wf                      inspect workflow runs

Commands that act on a house use the active house unless you pass --house. Global flags: --local targets localhost:8888, --model <provider/model> (-m) sets the local-pi model. Per-sandbox flags like --sandbox/-s are on the commands that use them. Run arbe <command> --help for subcommand flags.

Errors

A failed call exits non-zero and prints the error envelope — { code, message, recoverable } at the top level, plus optional suggestion and context. code is the stable switch; the HTTP status follows from it.

Terminal window
$ arbe http GET /api/threads/nonexistent12
{
  "code": "record.not_found",
  "message": "Not found",
  "recoverable": false
}
# exit 1

Client commands (thread, chat, …) render the same envelope as [<status> <code>] <message> on stderr; arbe http prints the raw body. With no token stored, commands short-circuit before any request: Authentication required. Run arbe auth login first.