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:

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

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

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/.

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).