Bee Box documentation · directory: https://beebox.run/docs/reference/ · index: https://beebox.run/docs/reference/index.md · root: https://beebox.run/llms.txt

# bbx Command Reference

These are the `bbx` commands most relevant to agents working in a box.

## bbx create

Create a new card from a template.

```
bbx create <path> [options]
```

The card type is inferred from the filename (e.g., `my-question.question.card` → question template).

**Options:**
- `-t, --template <name>` — Override template (usually auto-detected from filename)
- `-c, --content <text>` — Content for memo cards
- `-p, --prompt <text>` — Prompt for question cards
- `-m, --memo <text>` — Context/background for question cards
-  `-o, --options <items...>` — Options for select questions
- `-a, --attachment <path>` — Path to an attachment file
- `--commit` — Commit the new card immediately

**Examples:**
```bash
# Create a memo
bbx create _content/inbox/my-note.memo.card content="Remember to check the logs"

# Create a yes/no question
bbx create _bookkeeping/questions/confirm.question.card -t question-confirm \
  memo="The capture session is ready to archive" prompt="Archive it?"

# Create a scheduled script
bbx create _config/schedules/check.scheduled-script.card runs="bbx wakeup" cron="0 6 * * *"
```

### Available Templates

#### question

A multiple-choice question card

Card types: question

Arguments:
- `memo` — Context/background for the question
- `prompt` — The question to ask
- `options` — Answer options (at least 2)
- `directive` (optional) — What to do with the answer — creates a follow-up job using this text as instructions
- `learning` (optional) — Durable belief the answer teaches: {sink: guide|briefing|personality, ref?, proposal}
- `expires-after` (optional) — ISO-8601 duration overriding the default expiry window (e.g. P30D, PT12H)

#### question-text

A free-text question card

Card types: question

Arguments:
- `memo` — Context/background for the question
- `prompt` — The question to ask
- `directive` (optional) — What to do with the answer — creates a follow-up job using this text as instructions
- `learning` (optional) — Durable belief the answer teaches: {sink: guide|briefing|personality, ref?, proposal}
- `expires-after` (optional) — ISO-8601 duration overriding the default expiry window (e.g. P30D, PT12H)

#### question-confirm

A yes/no confirmation question card

Card types: question

Arguments:
- `memo` — Context/background for the question
- `prompt` — The question to ask
- `directive` (optional) — What to do with the answer — creates a follow-up job using this text as instructions
- `learning` (optional) — Durable belief the answer teaches: {sink: guide|briefing|personality, ref?, proposal}
- `expires-after` (optional) — ISO-8601 duration overriding the default expiry window (e.g. P30D, PT12H)

#### memo

A text memo card

Card types: memo

Arguments:
- `content` — The memo content text
- `source` (optional) — Source identifier (e.g., 'text', 'email')

#### voice-memo

A voice memo card (audio attached separately)

Card types: voice-memo, memo

#### guide

A generic guide card — triage rules, actions, experiments, reactions

Card types: guide

Arguments:
- `name` — Domain name (intake, calendar, drive, chat, or custom)

#### record

A record card — generic extracted unit from capture sessions

Card types: record

Arguments:
- `name` — Short identifying label for the record
- `description` (optional) — Description of the thing

#### recipe

A recipe card with ingredients, steps, and scaling support

Card types: recipe

Arguments:
- `title` — Recipe name
- `description` (optional) — What the dish is
- `servings` (optional) — Number of servings (default: 4)

#### scheduled-script

A scheduled script card — declarative scheduling for commands

Card types: scheduled-script

Arguments:
- `runs` — The command to execute
- `description` (optional) — Human-readable summary of what this schedule does
- `cron` (optional) — Cron expression (e.g., `0 6 * * *`)
- `at` (optional) — ISO datetime for one-shot execution
- `rrule` (optional) — iCalendar RRULE string
- `notBefore` (optional) — Minimum interval since last run (e.g., '5m', '1h')
- `onWakeup` (optional) — Also run during bbx wakeup
- `once` (optional) — Delete after successful execution
- `source` (optional) — Why this schedule exists
- `lock-group` (optional) — Named concurrency group

#### todo-view

A todos display surface — the box-wide plate, or a project-local subtree instance

Card types: todo-view

Arguments:
- `title` (optional) — Display title for the view
- `glob` (optional) — Glob scoping which cards to scan (default: this card's own directory subtree)
- `status` (optional) — Restrict to specific statuses (default: all)
- `assigned` (optional) — Restrict to todos with this exact `assigned` value

#### briefing

A briefing card — core situational context for a box or directory

Card types: briefing

#### doc

A generic typed document — use instead of .md when an agent creates a new document

Card types: doc

Arguments:
- `title` — Display title for the document
- `body` (optional) — Initial markdown body content

#### person

A person card — key people referenced from briefings

Card types: person

Arguments:
- `name` — Full name of the person
- `aliases` (optional) — Alias or nickname
- `role` (optional) — Relationship or function

#### place

A place card — a named location the box can recognize (Home, Office)

Card types: place

Arguments:
- `name` — Name of the place
- `aliases` (optional) — Another name for the place
- `address` (optional) — Human-readable address (street, city)

#### figure

An embeddable interactive figure (p5.js / three.js / D3 / canvas-loop); scaffolds a runnable starter sketch

Card types: figure

Arguments:
- `runtime` — Runtime: p5js | three | d3 | canvas-loop
- `title` (optional) — Display title

#### browser-task

A prompt for someone with a logged-in browser; the card is the inbox for what they find

Card types: browser-task

Arguments:
- `title` — Display title
- `source` — The URL the executor starts at
- `prompt` (optional) — The prompt body; omit to get the four-heading scaffold to fill in

#### concept-map

A module-scale knowledge graph (concepts as in-card nodes with typed edges)

Card types: concept-map

Arguments:
- `title` (optional) — Display title

#### course

A learning-experience manifest (binds a concept-map, exposition-plan, material, and progress)

Card types: course

Arguments:
- `title` (optional) — Display title

#### exposition-plan

A plan for how to present a subject (modalities + decisions, with the reasoning kept in)

Card types: exposition-plan

Arguments:
- `title` (optional) — Display title

#### lesson-plan

An ordered delivery flow (segments tagged interactive vs material, tied to the concept-map)

Card types: lesson-plan

Arguments:
- `title` (optional) — Display title

#### progress

A per-learner, evidence-backed record of understanding against a course's concept-map

Card types: progress

Arguments:
- `title` (optional) — Display title

#### dashboard

Canonical dashboard card. Restore only at _config/interface/dashboard.card; additional instances are invalid.

Card types: dashboard

#### settings

Canonical settings card. Restore only at _config/interface/settings.card; additional instances are invalid.

Card types: settings

#### browse

Canonical browse card. Restore only at _config/interface/browse.card; additional instances are invalid.

Card types: browse

#### questions

Canonical questions card. Restore only at _config/interface/questions.card; additional instances are invalid.

Card types: questions

#### landmarks

Canonical landmarks card. Restore only at _config/interface/landmarks.card; additional instances are invalid.

Card types: landmarks

#### history

Canonical history card. Restore only at _config/interface/history.card; additional instances are invalid.

Card types: history

#### inventory

Canonical inventory card. Restore only at _config/interface/inventory.card; additional instances are invalid.

Card types: inventory

#### admin

Canonical admin card. Restore only at _config/interface/admin.card; additional instances are invalid.

Card types: admin

## bbx mv

Move or rename a card, updating references in other cards.

```
bbx mv <source> <destination>
```

Use this instead of `git mv` or `mv` — it updates cross-references.

**Examples:**
```bash
# File an inbox item into its permanent home
bbx mv _content/inbox/Recipe.recipe.card _content/recipes/Recipe.recipe.card

# Archive a processed item
bbx mv _content/notes/Old_Note.doc.card _bookkeeping/archive/done/Old_Note.doc.card
```

## bbx rm

Soft-delete a card by moving it to `_bookkeeping/trash/`.

```
bbx rm <path>
```

## bbx validate

Validate a card against its schema.

```
bbx validate <path>
```

Always validate after creating or editing cards. Returns a non-zero exit code on failure.

## bbx view test

Render-test an agent-authored view (`views/<slug>.tsx`) in Node — no browser needed.

```
bbx view test <slug> [--path <card>] [--raw]
```

Compiles the view, loads the real cards its `dependencies` select, renders it once, and
prints the HTML — or, on failure, the error with a stack mapped to your `.tsx` source.
Use it to check a view after writing it. It's a synchronous render (no effects/async
helpers); see `node_modules/beebox/box-docs/views.md` for what it does and doesn't cover.

## bbx answer

Answer a pending question card.

```
bbx answer <path>
```

Interactively answers a question. For agents, it's often easier to edit the card XML directly
(set the `<answer>` element and `status="answered"`).

## bbx status

Show a summary of the box state — item counts in each directory, git status, etc.

```
bbx status
```

## bbx reactor

Process all pending jobs in `_bookkeeping/jobs/`.

```
bbx reactor [--dry-run]
```

The reactor finds all `*.job.card` files in `_bookkeeping/jobs/`, spawns an agent session,
and processes them according to each job type's instructions (from `.claude/rules/`).
The agent calls `bbx finish` for each completed job.

## bbx finish

Complete a job by deleting its card file and committing the deletion.

```
bbx finish <job-file>
```

Call this after all work for a job is done and committed. It only handles the job card deletion.

## bbx procedure

Run and manage declarative procedures. See `node_modules/beebox/box-docs/procedures.md` for details.

```bash
bbx procedure run <name-or-path>          # Run a procedure
bbx procedure run <name> --step <id>      # Run a single step
bbx procedure run <name> --dry-run        # Preview without executing
bbx procedure run <name> --directive "text" # Pass a directive to agents
bbx procedure list                        # List available procedures
bbx procedure status [run-dir]            # Show status of latest/specific run
```

The `<name-or-path>` argument can be a bare name (resolves to `_config/procedures/<name>.procedure.card`)
or a direct path to any `.procedure.card` file.

The `--directive` flag passes an opaque string that appears as `<directive>...</directive>` in every agent's
system prompt within the procedure. Use it to customize behavior without modifying the procedure card.

## bbx tick

Evaluate scheduled scripts and run any that are due.

```
bbx tick [--dry-run] [--script <name>] [--force] [--box <path>]
```

Checks all `_config/schedules/*.scheduled-script.card` files against their cron/at/rrule schedules.
Runs due scripts, updates last-run timestamps, and deletes one-shot (`once`) scripts after execution.

**Options:**
- `--dry-run` — Show which scripts would run without executing them
- `--script <name>` — Only evaluate a specific script (by filename stem)
- `--force` — Run the `--script` now, bypassing schedule, budget, and active-chat checks. Use this when the boxholder asks for a run from chat — a plain tick defers on the chat session itself. Running scripts/procedures and live lock-group holders still defer; force never preempts running work.
- `--box <path>` — Target a specific box instead of the current directory

Note: scripts with `on-wakeup="true"` also run during `bbx wakeup`, subject to their `not-before` interval.

## bbx scheduled

List all scheduled scripts and their status.

```
bbx scheduled
```

Shows each schedule's name, type (cron/at/rrule), next due time, last run, and flags (on-wakeup, once, enabled).

## bbx health

Show scheduled-task health: failing, overdue, blocked, inconclusive, or
invalid tasks, plus whether the scheduler daemon is alive.

```
bbx health [--json] [--all] [--box <path>]
```

Per task: status, last attempt vs last success (they diverge while failing),
consecutive-failure count, and the last error. `--all` includes disabled tasks.
Exit code 1 when anything is failing/overdue/invalid or the scheduler heartbeat
is stale, so scripts can gate on it. Deliberate skips (budget exhausted, missing
connector, disabled) show as blocked/disabled, never as failures. A task whose
last run completed its work but whose check reached no verdict shows as `?`
inconclusive — unknown, not broken — and does not affect the exit code.

## bbx scheduler

Manage the background scheduler daemon that runs `bbx tick` on a recurring basis.

```
bbx scheduler start [--interval <seconds>]  # Run daemon (foreground)
bbx scheduler add <path>                    # Add box to scheduler
bbx scheduler remove <path>                 # Remove box
bbx scheduler list                          # Show configured boxes
bbx scheduler status                        # Show boxes + launchd status
bbx scheduler log [--box <path>] [--limit <n>] [--errors] [--json]
bbx scheduler install                       # Install launchd plist
bbx scheduler uninstall                     # Remove launchd plist
```

The daemon polls every 60 seconds (configurable). Config at `~/.config/beebox/scheduler.json`.
Per-box logs are written to `.beebox/scheduler.jsonl` (JSONL, auto-rotated at 1MB).
Each log entry records which scripts ran/skipped/errored with timestamps and durations.
Agents can read `.beebox/scheduler.jsonl` to understand recent scheduling activity.

## bbx finalize

Run outbound connectors to flush pending output cards.

```
bbx finalize [-c, --connector <name>]
```

Symmetric counterpart to `bbx wakeup`. Sends any pending cards in `_bookkeeping/output/`
(e.g. telegram messages). Called automatically by the reactor after job processing,
or run manually to flush output.

## bbx scenario

Run scenario tests against boxes. Scenarios live in `~/src/boxes/scenarios/`.

```bash
bbx scenario list                          # List available scenarios
bbx scenario run <name>                    # Run a scenario
bbx scenario run <name> --dry-run          # Preview steps
```

## bbx chat

Talk to the live chat session.

- `bbx chat self-note "<body>" [--ref <path>] [--commit <hash>]` — Post an
  agent-authored record into the chat transcript without triggering a reply.
- `bbx chat screenshot [--session <id>] [--timeout <seconds>]` — Ask the
  user's connected chat tab for a screenshot of what they currently see in
  the box UI, and print the saved image path (Read it) plus a `fidelity:`
  line. Reach for it on visual/layout questions — how a card or custom view
  actually renders — where `whats-changed` (content) and reading the source
  can't help. It asks the user's browser, so instead of a path it may print
  one of `declined:` / `no-client:` / `timeout:` / `failed:` / `error:`
  telling you it was declined or unavailable. Defaults: the session from
  `BBX_CHAT_SESSION_ID`, a 45s wait.
- `bbx chat ask-about-audio "<question>" --message <id> [--context <text>]`
  — Ask an audio-capable model (Gemini) a question about a specific voice
  message (or `--file <path>` for any audio file). `--message` is
  required unless `--file` is given: read the `message-id="…"` attribute
  off the `<speech>` wrapper of the message you mean — never fabricate
  it. Claude can't listen to audio itself; use this when the exact audio
  matters — a mangled-but-important transcription, pronunciation, tone —
  not routine chat. The system's own transcript rides along automatically
  so the model can flag transcription flaws; `--context` supplies
  conversational background (what the message responds to), and
  `--transcript` overrides the known transcription.
- `bbx chat retranscribe --message <id> [--diarize] [--service <name>]` —
  Re-run a specific voice message (same `--message` targeting, or
  `--file <path>`) through the high-quality transcription pass
  (Whisper/Voxtral; default is the box's `hqService` config). For when
  the realtime transcript looks wrong and you just need the correct
  text — cheaper and more direct than `ask-about-audio`. Skip it when
  the message's wrapper already says `stt="hq"` — that text came from
  the better model already, so retranscribing has nothing to add.
  `--diarize` labels speakers. Prints the HQ transcript plus a `realtime-transcript:`
  line for comparison. A successful run shows the corrected text on the
  user's message automatically — don't paste it back unless asked.
- `bbx chat get-last-audio --message <id> [--out <path>]` — Fetch the raw
  recording of a specific voice message to a temp file; prints the path.
  Use when you need the file itself rather than an answer about it.

A bare command (no `--message`) errors — these commands never guess
which recording you mean. The recording is available only while the chat
tab that recorded it is open, and only for the last few voice messages
(the retention window).