How does the buzz CLI work?

HEAD
b483bbefix(mobile): tell same-name agents apart in Solo (#9321)
This post might have stale content, as HEAD is 245 commits ahead.

how does the buzz cli work? give me examples of things it can do

Avatar of openai/gpt-6.1-sol
GPT 6.1 Sol
commented

##What the Buzz CLI is

buzz is an agent-first command-line client for a Buzz relay. It exposes most of Buzz—channels, messages, users, workflows, repositories, projects, moderation, agent memory, and more—as scriptable subcommands.

The basic shape is:

buzz [global options] <group> <subcommand> [flags]

For example:

buzz messages send --channel <uuid> --content "Hello"

The current CLI groups are defined in crates/buzz-cli/src/lib.rs. Run:

buzz --help

to see the complete command tree, or:

buzz messages send --help

for detailed flags.

##Setup and authentication

Install it from the repository:

cargo install --path crates/buzz-cli

Select a relay and provide a Nostr private key:

export BUZZ_RELAY_URL="https://relay.example.com"
export BUZZ_PRIVATE_KEY="nsec1..."

You can also pass these as global options:

buzz --relay https://relay.example.com \
     --private-key nsec1... \
     channels list

On macOS and Linux, the CLI can instead ask the running Buzz desktop application to act as its credential provider:

buzz --relay https://relay.example.com auth desktop pair
buzz auth desktop list

The credential-selection behavior is documented in crates/buzz-cli/README.md.

##How it works internally

  1. Clap parses the command tree.
  2. The CLI chooses the relay from --relay, BUZZ_RELAY_URL, a paired Desktop instance, or the local default http://localhost:3000.
  3. It resolves an identity from --private-key/BUZZ_PRIVATE_KEY or Buzz Desktop.
  4. Command handlers construct typed, signed Nostr events or Nostr filters.
  5. Reads generally go through the relay’s authenticated HTTP /query bridge; stored writes submit signed events through /events. Some ephemeral events use WebSockets.
  6. Every protected HTTP request gets a fresh NIP-98 proof. Optional NIP-OA delegation and NIP-FI federated-identity evidence are also supported.

The dispatch is visible in src/lib.rs, request authorization in src/client.rs, and querying in src/client.rs.

Output is designed for automation:

buzz channels list | jq '.[].name'

Available output modes include:

buzz --format json messages get --channel <uuid>
buzz --format compact messages get --channel <uuid>
buzz --format agent messages get --channel <uuid>

Errors are structured JSON on stderr. Exit codes distinguish invalid input, network errors, authentication failures, other errors, and write conflicts.


##Examples

###Create and inspect channels

CHANNEL=$(
  buzz channels create \
    --name "release-planning" \
    --type stream \
    --visibility open |
  jq -r '.channel_id'
)

buzz channels list | jq .
buzz channels get --channel "$CHANNEL" | jq .
buzz channels topic --channel "$CHANNEL" --topic "Planning the next release"
buzz channels members --channel "$CHANNEL" | jq .

You can also join, leave, archive, update, delete, and manage membership:

buzz channels join --channel "$CHANNEL"

buzz channels add-member \
  --channel "$CHANNEL" \
  --pubkey <member-pubkey> \
  --role member

###Send and read messages

SEND=$(
  buzz messages send \
    --channel "$CHANNEL" \
    --content "The release candidate is ready."
)

EVENT_ID=$(echo "$SEND" | jq -r '.event_id')

buzz messages get --channel "$CHANNEL" --limit 20 | jq .

Read content safely from stdin—useful for Markdown, code, and shell metacharacters:

buzz messages send \
  --channel "$CHANNEL" \
  --content - < announcement.md

###Work with threads

buzz messages send \
  --channel "$CHANNEL" \
  --content "I reviewed it." \
  --reply-to "$EVENT_ID"

buzz messages thread \
  --channel "$CHANNEL" \
  --event "$EVENT_ID" |
jq .

It can also resolve a canonical Buzz message link:

buzz messages thread \
  --link "buzz://message?channel=$CHANNEL&id=$EVENT_ID"

###Search and edit messages

buzz messages search --query "release candidate" --limit 10 | jq .

buzz messages search \
  --query "architecture" \
  --author <pubkey-or-name> \
  --since <unix-timestamp> |
jq .

buzz messages edit \
  --event "$EVENT_ID" \
  --content "The release candidate is ready for final review."

buzz messages delete --event "$EVENT_ID"

###Reactions and forum voting

buzz reactions add --event "$EVENT_ID" --emoji "👍"
buzz reactions get --event "$EVENT_ID" | jq .
buzz reactions remove --event "$EVENT_ID" --emoji "👍"

buzz messages vote --event <forum-post-event-id> --direction up

###Report abusive content privately

Reports are sent to community moderators rather than posted in the channel:

buzz messages report \
  --event "$EVENT_ID" \
  --reason spam \
  --note "Repeated unsolicited advertising"

buzz messages report \
  --pubkey <pubkey> \
  --reason impersonation

###Maintain a channel canvas

buzz canvas set \
  --channel "$CHANNEL" \
  --content "# Release plan"

buzz canvas set \
  --channel "$CHANNEL" \
  --content - < release-plan.md

buzz canvas get --channel "$CHANNEL"
buzz canvas history --channel "$CHANNEL"

###Profiles, presence, and status

buzz users get | jq .
buzz users get --pubkey <pubkey> | jq .

buzz users set-profile \
  --display-name "Release Bot" \
  --about "Coordinates release work"

buzz users set-presence --status online

buzz users set-status \
  --text "Preparing the release" \
  --emoji "🚀" \
  --expires 2h

buzz users status --pubkey <pubkey-or-name> | jq .

###Direct messages

buzz dms open --pubkey <recipient-pubkey>
buzz dms list | jq .

DM groups can contain multiple people:

buzz dms open \
  --pubkey <person-one> \
  --pubkey <person-two>

###Workflows

buzz workflows list --channel "$CHANNEL" | jq .

buzz workflows trigger --workflow <workflow-uuid>

buzz workflows runs --workflow <workflow-uuid> | jq .

buzz workflows approve --token <approval-token>

buzz workflows approve \
  --token <approval-token> \
  --approved false \
  --note "Needs another security review"

###Team knowledge-base notes

cat note.md | buzz notes set \
  --name release-process \
  --title "Release Process" \
  --summary "How releases are prepared" \
  --tag release \
  --content -

buzz notes get --name release-process | jq .
buzz notes ls --tag release | jq .
buzz notes ls --author all --limit 20 | jq .
buzz notes rm --name release-process

###Persistent agent memory

The mem commands implement persistent, named agent memories:

buzz mem ls
buzz mem set current-task "Investigate failing release workflow"
buzz mem get current-task
buzz mem hash current-task
buzz mem rm current-task

Memory can be updated through a unified diff with conflict protection:

buzz mem patch current-task \
  --base-hash <sha256> < update.patch

###Repositories and branch protection

buzz repos list | jq .
buzz repos get --id my-repo | jq .

buzz repos protect set \
  --id my-repo \
  --ref refs/heads/main \
  --push admin \
  --no-force-push \
  --no-delete

buzz repos protect list --id my-repo | jq .

Manage the default branch with optimistic conflict detection:

buzz repos default-branch get \
  --owner <owner-pubkey> \
  --id my-repo

buzz repos default-branch set \
  --owner <owner-pubkey> \
  --id my-repo \
  --branch main

###Upload files

buzz upload file ./diagram.png | jq .

The relay returns a Blossom descriptor containing fields such as the public URL, SHA-256 hash, MIME type, and size. Media authentication and metadata handling live in src/client.rs.

###Inspect huddles

These commands reconstruct huddle state from relay lifecycle events; they do not join or start calls:

buzz huddles list --channel "$CHANNEL" --active | jq .

buzz huddles participants \
  --channel "$CHANNEL" \
  --huddle <huddle-id> |
jq .

###Organize the Desktop sidebar

These settings synchronize with Buzz Desktop:

buzz sidebar sections create --name "Engineering" --icon "🛠"
buzz sidebar sections move --section "Engineering" --channel "$CHANNEL"

buzz sidebar stars add --channel "$CHANNEL"
buzz sidebar mutes add --channel <noisy-channel>

buzz sidebar sort set --group "Engineering" --mode recent
buzz sidebar sections list | jq .

The CLI’s README contains the broader command reference and additional examples: crates/buzz-cli/README.md.


END OF POST

How does the buzz CLI work? — block/buzz