# CLI

> For sandbox/environment/secret commands, see [runtime](./system/runtime.md).

`arbe` — agent harness, task tracker, build loop. See [architecture](architecture.md) 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

```sh
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](./system/releases.md).

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.

```sh
$ 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.`