CLI Reference: Blackboard (bb)
Commands for the shared key-value blackboard.
The blackboard is a daemon-global shared key-value store. Any agent with bb.read / bb.write capabilities can read and write it. Values are JSON and may have optional TTLs.
ash bb read
Read a value from the blackboard.
ash bb read <agent-id> <key>
Returns the current JSON value and its version number. Returns an error if the key does not exist.
Example:
ash bb read <agent-id> shared/config
ash bb write
Write a value to the blackboard.
ash bb write <agent-id> <key> <value-json> [--ttl <seconds>]
| Argument/Flag | Description |
|---|---|
agent-id | Agent ID performing the write (must have bb.write) |
key | Arbitrary string key (supports /-separated namespacing by convention) |
value-json | JSON value to store |
--ttl | Optional time-to-live in seconds; key expires automatically |
Examples:
ash bb write <agent-id> status/phase '"running"'
ash bb write <agent-id> config/batch-size 100 --ttl 3600
ash bb cas
Compare-and-swap: atomically update a key only if the current value matches the expected value.
ash bb cas <agent-id> <key> <expected-json> <new-value-json> [--ttl <seconds>]
Use "null" as expected-json to only succeed when the key does not exist.
Example:
# Set "locked" to true only if it is currently false
ash bb cas <agent-id> task/lock false true
Returns success if the swap was applied, or an error with the current value if the expected value did not match.
ash bb delete
Delete a key from the blackboard.
ash bb delete <agent-id> <key>
Requires bb.write capability. No-op if the key does not exist.
ash bb list
List blackboard keys matching an optional glob pattern.
ash bb list <agent-id> [--pattern <glob>]
| Flag | Description |
|---|---|
--pattern | Glob pattern to filter keys (e.g. status/*, config/**) |
Examples:
ash bb list <agent-id>
ash bb list <agent-id> --pattern "status/*"