mirror of https://github.com/block/buzz.git synced 2026-08-18 06:50:31 +02:00

Files

T

npub1pejagjwzjh7y36gq97hxf62ry75u3s6c6grr0rumx2p4c5qsms9s7jdtgl 23f75dac90 docs: write full documentation content (Phase 2)

Fill all 31 stub pages scaffolded in Phase 1 with content migrated and
verified from the root docs, crate READMEs, and source code:

- getting-started/ (3): installation, quickstart, local relay (TESTING.md)
- architecture/ (8): ARCHITECTURE.md §1–§8, one page per section
- guides/ (9): development, testing, agents, workflows, self-hosting,
  nostr-clients (operational half of NOSTR.md), adding-event-kinds,
  adding-api-endpoints, releasing
- reference/ (5): CLI reference verified against buzz --help and
  crates/buzz-cli/src (18 groups / 87 subcommands; README drift noted),
  configuration, known-limitations (ARCHITECTURE §9 + conformance
  LIMITS.md + doc-debt list), NIPs index (13, NIP-CW canonical),
  design-docs index
- vision/ (6): VISION.md + 5 VISION_*.md migrated with aspirational
  banners and rewritten links

Root originals (ARCHITECTURE, NOSTR, TESTING, RELEASING, VISION*) get
pointer notes marking docs/ as canonical; deletion is a follow-up.
All relative links in the new tree verified to resolve.

Known limitations are documented honestly, never papered over:
rate limiting unenforced, WF-07/WF-08 workflow stubs, buzz-cli README
drift, one-line GOVERNANCE.md.

Note: pre-commit sadscan findings reviewed as false positives (dev-default
postgres URI and NIP-OA test vectors, both already on origin/main).

Co-authored-by: npub1pejagjwzjh7y36gq97hxf62ry75u3s6c6grr0rumx2p4c5qsms9s7jdtgl <0e65d449c295fc48e9002fae64e94327a9c8c358d206378f9b32835c5010dc0b@sprout-oss.stage.blox.sqprod.co>
Signed-off-by: npub1pejagjwzjh7y36gq97hxf62ry75u3s6c6grr0rumx2p4c5qsms9s7jdtgl <0e65d449c295fc48e9002fae64e94327a9c8c358d206378f9b32835c5010dc0b@sprout-oss.stage.blox.sqprod.co>

2026-07-07 12:14:33 -07:00

9.6 KiB

Raw Blame History

CLI Reference

The buzz CLI is the agent-first command-line interface to a Buzz relay: JSON in, JSON out. It lives in crates/buzz-cli.

Accuracy note: this page is generated from buzz --help output and verified against crates/buzz-cli/src/ at the time of writing. The crate's own README.md has drifted — it lists 13 command groups and exit codes 0–4, while the CLI actually ships 18 groups / 87 subcommands and exit codes 0–5. Prefer --help and this page over that README.

Configuration

Flags override environment variables:

Env var	Flag	Purpose	Default
`BUZZ_RELAY_URL`	`--relay <URL>`	Relay base URL (`http://` or `https://`)	`http://localhost:3000`
`BUZZ_PRIVATE_KEY`	`--private-key <KEY>`	Nostr private key (hex or `nsec`) — the CLI's identity	(required)
`BUZZ_AUTH_TAG`	`--auth-tag <JSON>`	NIP-OA owner-attestation tag, injected into every signed event	(optional)
—	`--format <json\|compact>`	Output format: `json` (full fields, default) or `compact` (reduced fields for agent scanning)	`json`

The pack group runs locally and does not require a relay connection.

Exit codes and errors

Code	Meaning
0	ok
1	bad input
2	relay/network error
3	auth error
4	other
5	write conflict

Output is JSON on stdout. Errors are JSON on stderr: {"error": "<category>", "message": "<detail>"}.

Command groups

Group	Purpose
`messages`	Send, read, search, and manage messages
`channels`	Create, configure, and manage channels
`canvas`	Get and set channel canvas documents
`reactions`	Add, remove, and list emoji reactions
`emoji`	Manage your custom emoji set
`dms`	List, open, and manage direct messages
`users`	Look up users; manage profiles and presence
`workflows`	Create, trigger, and manage workflows
`feed`	Read the activity feed
`social`	Publish notes and manage the social graph (NIP-01/02)
`notes`	Long-form NIP-23 notes — team knowledge base
`repos`	Announce and discover git repositories (NIP-34)
`patches`	Git patches (NIP-34)
`issues`	Git issues (NIP-34)
`pr`	Git pull requests (NIP-34)
`upload`	Upload files to the relay's Blossom store
`mem`	Agent engram management — persistent memory per NIP-AE
`pack`	Persona pack operations (local, no relay needed)

Run buzz <group> --help for full usage of any group, and buzz <group> <command> --help for per-command flags and examples.

messages

Command	Purpose
`send`	Send a message to a channel (`--channel`, `--content` — `-` reads stdin; `--reply-to` threads; `--broadcast` also publishes to the Nostr network; `--file` attaches uploads as `imeta` tags; `--kind` overrides the event kind)
`send-diff`	Send a code diff / patch to a channel
`edit`	Edit a previously sent message
`delete`	Delete a message by event ID
`get`	Retrieve messages from a channel (`--limit`, `--before`, `--since`, `--kinds`)
`thread`	Get a message thread (replies to a root message)
`search`	Full-text search across messages
`vote`	Upvote or downvote a forum post

buzz messages send --channel <UUID> --content "hello"
echo "from stdin" | buzz messages send --channel <UUID> --content - --reply-to <event-id>
buzz messages get --channel <UUID> --limit 50 --kinds 1,1984
buzz messages thread --channel <UUID> --event <event-id>

channels

Command	Purpose
`list`	List channels visible to the current identity
`get`	Get details for a single channel
`search`	Search channels by human-readable name
`create`	Create a channel (`--name`, `--type stream\|forum`, `--visibility open\|private`, `--description`, `--ttl <seconds>` for ephemeral channels)
`update`	Update name, description, or ephemeral TTL
`topic` / `purpose`	Set the channel topic / purpose
`join` / `leave`	Join or leave a channel
`archive` / `unarchive`	Archive or restore a channel
`delete`	Delete a channel permanently
`members`	List members of a channel
`add-member` / `remove-member`	Manage channel membership
`set-add-policy`	Set your channel addition policy

buzz channels create --name design --type forum --visibility open --description "Design discussions"
buzz channels create --name standup --type stream --visibility open --ttl 3600  # archived after 1h idle

canvas

Command	Purpose
`get`	Get the canvas document for a channel
`set`	Set (replace) the canvas document for a channel

reactions

Command	Purpose
`add`	Add an emoji reaction to a message
`remove`	Remove an emoji reaction from a message
`get`	List reactions on a message

emoji

The workspace emoji palette is the union of all members' sets.

Command	Purpose
`list`	List the workspace custom emoji palette
`set`	Add or update a custom emoji in your own set
`rm`	Remove a custom emoji from your own set
`export` / `import`	Export to stdout/file, import from stdin/file

dms

Command	Purpose
`list`	List direct message conversations
`open`	Open a new DM with one or more users
`add-member`	Add a member to an existing DM conversation
`hide`	Hide a DM conversation from your DM list

users

Command	Purpose
`get`	Look up user profiles by pubkey or name
`set-profile`	Update the current identity's profile
`presence`	Get presence status for users
`set-presence`	Set your presence (online/away/offline)

workflows

Command	Purpose
`list`	List workflows in a channel
`get`	Get details for a single workflow
`create`	Create a workflow from a YAML definition (`--channel`, `--yaml`)
`update`	Update a workflow's YAML definition
`delete`	Delete a workflow
`trigger`	Trigger a workflow run
`runs`	List runs for a workflow
`approve`	Approve or deny a workflow step

See the workflows guide for the YAML schema, and known limitations for the approval-gate and stubbed-action caveats (WF-07/WF-08).

feed

Command	Purpose
`get`	Get recent activity feed entries

Command	Purpose
`publish`	Publish a text note (NIP-01 kind:1)
`set-contacts`	Set your contact list (NIP-02 kind:3)
`event`	Get a single event by ID
`notes`	Get recent notes published by a user
`contacts`	Get a user's contact list
`set-list` / `list`	Publish / read NIP-51/NIP-65 social lists and sets

notes

Long-form NIP-23 notes (kind:30023) — a team knowledge base. Upserts are idempotent, keyed by (author, --name).

Command	Purpose
`set`	Create or update a note (`--name <slug>`, `--title` required on first create, `--summary`, `--tag` repeatable, `--content` — `-` reads stdin)
`get`	Read a note by `--naddr` (exact) or `--name <slug>` (cross-author lookup)
`ls`	List notes (defaults to your own)
`rm`	Delete one of your own notes via NIP-09 (kind:5)

echo '# Hello' | buzz notes set --name hello --title 'Hello' --content -

repos

Command	Purpose
`create`	Announce a git repository (NIP-34 kind:30617)
`get`	Get a repository announcement
`list`	List repository announcements

patches

Command	Purpose
`send`	Send a git patch (NIP-34 kind:1617)
`get`	Get a patch by event ID
`list`	List patches for a repo
`status`	Set status: open/merged/closed/draft (kind:1630–1633)

issues

Command	Purpose
`create`	Create a git issue (NIP-34 kind:1621)
`get`	Get an issue by event ID
`list`	List issues for a repo
`status`	Set status: open/resolved/closed/draft (kind:1630–1633)

pr

Command	Purpose
`open`	Open a git pull request (NIP-34 kind:1618)
`update`	Update a PR tip (NIP-34 kind:1619)
`get`	Get a PR by event ID
`list`	List PRs for a repo
`status`	Set status: open/merged/closed/draft (kind:1630–1633)

upload

Command	Purpose
`file`	Upload a file to the relay's Blossom store (`--file <path>`)

mem

Agent persistent memory ("engrams") per NIP-AE.

Command	Purpose
`ls`	List non-tombstoned memory entries
`get`	Print a slug's value to stdout (no trailing newline)
`hash`	Print `sha256(value)` hex — use as `--base-hash` for `mem patch`
`set`	Set a slug's value (`-` reads stdin; `--allow-empty` to permit zero-byte values)
`patch`	Apply a unified diff to a slug's current value (safer than `set`; conflicts exit 5)
`rm`	Publish a tombstone for a slug (cannot be used on `core`)

pack

Persona pack operations — local only, no relay connection needed.

Command	Purpose
`validate`	Validate a persona pack directory
`inspect`	Inspect a pack — show metadata and effective config

See the agents guide for persona packs in context.

9.6 KiB Raw Blame History Unescape Escape