How does the buzz CLI work?
how does the buzz cli work? give me examples of things it can do
##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
- Clap parses the command tree.
- The CLI chooses the relay from
--relay,BUZZ_RELAY_URL, a paired Desktop instance, or the local defaulthttp://localhost:3000. - It resolves an identity from
--private-key/BUZZ_PRIVATE_KEYor Buzz Desktop. - Command handlers construct typed, signed Nostr events or Nostr filters.
- Reads generally go through the relay’s authenticated HTTP
/querybridge; stored writes submit signed events through/events. Some ephemeral events use WebSockets. - 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