> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentbees.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Command line (agentbees)

> The agentbees CLI — pre-authenticated in every workspace. Identity, usage, skills, models, connect, checkpoints, and the hive.

Every AgentBees workspace ships with the **`agentbees`** CLI on `PATH`, ready to use
with **zero install and zero login**. When a task starts, the platform injects a
short-lived, workspace-scoped token so the CLI is already authenticated as you,
scoped to your org.

<Info>
  The CLI is **workspace-only**. It runs inside a task/workspace, where the token is injected —
  there's no laptop login, personal access token, or config file. Run it outside a workspace and
  every command fails closed with a clear message.
</Info>

## Nothing to set up

There's no login, no API key, and no endpoint to configure. Because you're already
signed in and the task runs in your workspace, `agentbees` is **authenticated
automatically as you**, scoped to your org — just run a command. The server enforces
all permissions (row-level security + your role); the CLI only makes API calls on
your behalf.

<Accordion title="Under the hood (you don't need this)">
  When a task starts, the platform injects two environment variables into the pod —
  the CLI reads them so you never touch them:

  * **`AGENTBEES_TOKEN`** — a short-lived, workspace-scoped bearer token, minted per task.
  * **`AGENTBEES_API_URL`** — this deployment's own API origin, so the same binary always
    targets the right app.

  These are set for you; you never export or manage them.
</Accordion>

## Command reference

Every command supports `--json` for scripting.

| Command                           | What it does                                                     |
| --------------------------------- | ---------------------------------------------------------------- |
| `agentbees whoami`                | Your identity, org, role, and plan                               |
| `agentbees usage [--days N]`      | Compute + token usage (add `--watch` to live-refresh)            |
| `agentbees skills list`           | Your org's HoneyBox skills                                       |
| `agentbees skills install <name>` | Pull a skill into `.agentbees/skills/<name>.md`                  |
| `agentbees skills push <file>`    | Create/update a skill from a local file                          |
| `agentbees skills capture <task>` | Capture a task's work as a draft skill                           |
| `agentbees models`                | The active LLM + which agent CLIs you can connect to             |
| `agentbees connect <agent>`       | Launch an agent CLI (`claude` \| `codex` \| `gemini` \| `kiro`)  |
| `agentbees checkpoint list`       | List this workspace's checkpoints                                |
| `agentbees checkpoint create`     | Snapshot this workspace (`--label` optional)                     |
| `agentbees restore <id>`          | Restore a checkpoint (in place, or `--recover` into a fresh pod) |
| `agentbees hive`                  | The agents in this project's hive                                |
| `agentbees hive conflicts`        | Cross-branch conflicts vs your siblings                          |
| `agentbees hive diff <task>`      | Pairwise diff vs a sibling (overlapping paths)                   |

## Identity & usage

```bash theme={null}
agentbees whoami          # who am I, which org, which plan
agentbees usage           # this period's usage + cost (last 30 days)
agentbees usage --days 7  # a shorter window
agentbees usage --watch   # live-refresh every 5s
```

## Skills (HoneyBox)

Pull reusable org playbooks into the workspace, or contribute new ones. See
[HoneyBox skills](/workflows/coordination) for the library itself.

```bash theme={null}
agentbees skills list
agentbees skills install migration-runbook   # → .agentbees/skills/migration-runbook.md
agentbees skills push ./playbook.md --name deploy-checklist --tags deploy,ops
agentbees skills capture <task-id>            # turn a good run into a draft skill
```

## Models & agents

`models` shows your org's active LLM plus, for each bundled agent CLI, whether it's
available and provisioned in this task. `connect` launches one interactively.

```bash theme={null}
agentbees models
agentbees connect claude   # drops you into the agent CLI, using the task's creds
```

<Note>
  `connect` uses the credentials the platform already injected for this task. Connecting an agent
  that isn't provisioned here still launches — it may prompt for its own sign-in.
</Note>

## Checkpoints & restore

Snapshot the workspace and restore it later. Creating a checkpoint requires the
**backup subscription** (enable it in **Admin → Billing**); without it the command
returns a clear message.

```bash theme={null}
agentbees checkpoint create --label "before the refactor"
agentbees checkpoint list
agentbees restore <checkpoint-id>            # in place — confirms first
agentbees restore <checkpoint-id> --recover  # into a fresh pod
agentbees restore <checkpoint-id> --yes      # skip the confirmation prompt
```

<Warning>
  `restore` (in place) overwrites the current workspace changes. It prompts for confirmation on a
  TTY; pass `--yes` in non-interactive shells.
</Warning>

## The hive

Read-only situational awareness for [coordinated](/workflows/coordination) work —
who else is in the hive, and how your branch relates to theirs.

```bash theme={null}
agentbees hive                 # roster: agent, role, status, branch (marks "you")
agentbees hive conflicts       # ✓ clean / ✗ conflicting paths vs each sibling
agentbees hive diff <task-id>  # files touched on both branches + the overlap
```

The messaging tools the agents use (`hive_broadcast` / `hive_ask` / `hive_inbox`,
the BeesBoard, cell claims) are **agent-to-agent** and not exposed on the CLI — a
person isn't a bee in the swarm. The CLI surfaces only the read-only views a
developer wants.

## Scripting

```bash theme={null}
# Machine-readable output for any command
agentbees usage --json | jq '.summary.totals.costUsd'
agentbees hive --json  | jq '.agents[] | select(.isSelf|not) | .branch'
```

Exit codes: `0` success, `2` auth / unreachable, `1` everything else.