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

Artifacts

List and fetch source artifacts — meeting transcripts, email threads, call recordings, documents — that the substrate has extracted into durable memory.

butterbase substrate artifacts list

butterbase substrate artifacts list --kind meeting_transcript --limit 25
butterbase substrate artifacts list --q "billing migration" --json | jq '.artifacts[].id'

Option	Type	Default
--kind <k>	string	all
--q <query>	string (FTS over title+summary+content)	none
--limit <n>	int (1–200)	50
--json	flag	table output

butterbase substrate artifacts get <id>

Fetch a single artifact, including its full content.

butterbase substrate artifacts get art_01H...
butterbase substrate artifacts get art_01H... --json | jq -r '.content'

Memory

Full-text search across decisions, commitments, learnings, and source artifacts.

<query> is optional. When omitted, the command returns the most recent items across the selected kinds ordered by recency, capped by --limit.

# search with a query
butterbase substrate memory "OKR planning Q3" --limit 10

# list most recent items (no query)
butterbase substrate memory --limit 20

# require all words (default)
butterbase substrate memory "billing migration" --match and

# match any word
butterbase substrate memory "billing migration" --match or

# require adjacent words (phrase search)
butterbase substrate memory "billing migration" --match phrase

Option	Type	Default
<query>	string (FTS query; omit to list all)	none
--match <mode>	and | or | phrase	and
--kinds <k,...>	comma-separated: decisions, commitments, learnings, source_artifacts	all
--limit <n>	int (1–200)	20
--json	flag	table output

Each result row includes id, kind, title, body_text, rank (null when no query), updated_at, source_artifact_id, supersedes, and status.

{
  "results": [
    {
      "id": "dec_01…",
      "kind": "decision",
      "title": "Adopt substrate",
      "body_text": "agents need shared memory",
      "rank": 0.18,
      "updated_at": "2026-05-31T…",
      "source_artifact_id": null,
      "supersedes": null,
      "status": "active"
    }
  ]
}

Memory list (chronological browse)

Chronological browse across decisions, commitments, learnings, and source artifacts with structural filters. Results are ordered by updated_at DESC. There is no relevance ranking.

butterbase substrate memory-list --source-artifact-id art_01H... --kinds decisions,commitments,learnings --superseded false --limit 50

Flag	Type	Default
--kinds <k,...>	comma-separated: decisions, commitments, learnings, source_artifacts	all
--source-artifact-id <id>	string — restrict to rows linked to this source artifact (source_artifact rows excluded when set)	none
--superseded <bool>	true | false — when false, excludes superseded decisions and expired commitments	include all
--before <timestamp>	ISO timestamp keyset cursor (paste next_before from a previous response)	none
--limit <n>	int (1–100)	25
--json	flag	table output

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