@lambdacurry/arbor

The Arbor CLI — a shared workspace for people and agents. It's the human + headless-agent write path over Arbor's one guarded operation surface: every command resolves your identity from your token server-side (the CLI never asserts who you are) and runs through the same /api operations the web app and MCP clients use.

Install

No install required — run it on demand:

npx @lambdacurry/arbor whoami

…or install it globally:

npm i -g @lambdacurry/arbor
arbor whoami

Authenticate

Point the CLI at your Arbor instance and give it a credential — a personal access token (acts as you) or an agent key (acts as the agent). Either works headlessly via env, or persist it:

# Headless (CI / agents): env only, no stored config
ARBOR_API_URL=https://your-arbor.example ARBOR_TOKEN=<token> arbor inbox

# …or persist it to ~/.arbor/config.json (chmod 600)
arbor auth <token> --url https://your-arbor.example
arbor whoami

Named profiles

Keep human/owner and agent credentials in separate owner-only files instead of copying tokens or switching one shared config. Named profile credentials live under ~/.arbor/profiles/; the token-free local registry stores only the configured default profile. Arbor still resolves the actual identity from the selected credential server-side.

# Save credentials into separate profile files.
arbor auth <agent-token> --profile agent
arbor auth <owner-token> --profile owner

# Ordinary commands now use the least-privileged agent profile.
arbor profile set-default agent
arbor whoami

# Explicitly use the owner for one command only; the next command returns to the default.
arbor whoami --profile owner
arbor whoami

# Automation can select the same one-command profile without changing the default.
ARBOR_PROFILE=owner arbor whoami

Without ARBOR_CONFIG, selection precedence is --profile → ARBOR_PROFILE → configured default → legacy ~/.arbor/config.json. When ARBOR_CONFIG is set by itself it is decisive and bypasses the configured default; combining it with --profile or ARBOR_PROFILE fails as ambiguous instead of guessing. ARBOR_TOKEN and ARBOR_API_URL remain headless overrides after the credential target is selected.

Profile management never prints credential material:

arbor profile list
arbor profile show agent
arbor profile set-default agent
arbor profile clear-default
arbor profile delete owner

Agent self-registration (AD-109)

An agent can register itself with a device-code-style handshake. A human mints a one-time pairing key in the Arbor web app (Settings → "Have an agent register itself") and hands it to the agent. The agent then:

npx @lambdacurry/arbor connect <pairing-key>

This prints a URL + short code to relay to the human, who approves it in their logged-in session. On approval the agent receives its own key (saved to ~/.arbor/config.json) and acts as a managed, collaborate-only member of the org thereafter.

Output contract (agent-friendly)

Every command takes --json to emit a stable { ok, data | error, meta } envelope on stdout (with structured error codes and agent-mode exit codes); advisory/human text goes to stderr. A failure envelope adds the server's granular reason — validation.missing_field, limit.exceeded, conflict.state, … — beside the coarse code, optionally with field, limit, retryable, phase, and bounded sanitized provider lifecycle diagnostics (AD-237/261). --quiet (auto under --json or a pipe) silences the advisory stream. --fields a,b,list:N projects a result; --limit/--cursor paginate list commands.

arbor inbox --json --limit 20
arbor thread get <id> --json --fields title,contributions:5

Run arbor help (or arbor help --json for the machine catalog) for the full command surface.

License

MIT © Lambda Curry