# @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:

```bash
npx @lambdacurry/arbor whoami
```

…or install it globally:

```bash
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:

```bash
# 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.

```bash
# 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:

```bash
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:

```bash
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.

```bash
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