---
title: butterbase substrate
description: Manage Butterbase substrate from the command line — memory, actions, attention rules, outbox, and settings.
---

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

```bash
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.

```bash
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.

```bash
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.

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

## Entities

```bash
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.

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

## Outbox

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

## Attention rules

```bash
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.

```bash
butterbase substrate snapshots --days 7
```

## Settings

```bash
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:

```bash
butterbase keys generate --substrate
```
