butterbase substrate

butterbase substrate

The butterbase substrate command group gives you scriptable access to the Butterbase substrate: the per-user memory + action coordination plane that backs your AI agents.

It uses your active Butterbase API key. The key must be substrate-scoped — generate one with:

butterbase keys generate --substrate
export BUTTERBASE_API_KEY="bb_sk_..."

All commands accept --json to emit the raw API response (suitable for piping to jq).

Action ledger

butterbase substrate ledger

List actions in the substrate ledger.

butterbase substrate ledger --status executed --capability send_email_draft --limit 25
butterbase substrate ledger --before 2026-05-28T00:00:00Z --json | jq '.actions[].id'

butterbase substrate propose <capability>

Propose a new action.

echo '{"to":"hello@example.com","subject":"hi","body":"hi"}' > payload.json
butterbase substrate propose send_email_draft --payload @payload.json --idempotency-key my-key-1

butterbase substrate approve <id> / butterbase substrate reject <id> [--reason]

Approve or reject a pending action.

butterbase substrate approve act_01H...
butterbase substrate reject  act_01H... --reason "policy mismatch"

Entities

butterbase substrate entities list --type person
butterbase substrate entities get  ent_01H...
echo '{"display_name":"Renamed"}' > patch.json
butterbase substrate entities update ent_01H... --patch @patch.json

Memory

Full-text search across decisions, commitments, learnings, and principles.

butterbase substrate memory "OKR planning Q3" --limit 10

Outbox

butterbase substrate outbox list --state pending
butterbase substrate outbox cancel ob_01H...
butterbase substrate outbox retry  ob_01H...

Attention rules

butterbase substrate rules list --enabled
butterbase substrate rules get rule_01H...

echo '{
  "name": "weekly digest",
  "trigger_cron": "0 9 * * 1",
  "condition_mode": "snapshot_predicate",
  "condition": { ">": [{ "var": "entity_count" }, 0] },
  "action_capability": "send_email_draft",
  "action_payload_template": {
    "to": "me@example.com",
    "subject": "Weekly digest",
    "body": "{{entity_count}} entities."
  }
}' > rule.json

butterbase substrate rules create --file @rule.json
butterbase substrate rules enable  rule_01H...
butterbase substrate rules disable rule_01H...
butterbase substrate rules firings rule_01H... --limit 50
butterbase substrate rules delete  rule_01H...

Snapshots

Daily state snapshots used by attention-rule conditions.

butterbase substrate snapshots --days 7

Settings

butterbase substrate settings show
butterbase substrate settings yolo on
butterbase substrate settings yolo off

Output formats

• Default: compact, human-readable table where applicable.
• --json: raw HTTP response body. Useful for scripting.

Authentication errors

If a command returns your active key is app-scoped, generate a substrate-scoped key:

butterbase keys generate --substrate