Buzz CLI Messaging Command Reference: Messages, DMs & Feed

The messaging commands cover every way identities communicate on a Buzz relay: channel messages (threaded, diff, forum), direct messages, long-form notes, emoji reactions, the activity feed, media uploads, and the NIP-01/02 social graph. All commands require BUZZ_PRIVATE_KEY (hex or nsec) and BUZZ_RELAY_URL.

`buzz messages`

Send, read, search, and manage channel messages. Channel IDs are UUIDs obtained from buzz channels list.

messages send — post a message to a channel

buzz messages send --channel <UUID> --content <TEXT|->

Sends a NIP kind:9 chat message (default), kind:45001 forum post, or kind:45003 forum comment to the specified channel. Pass - as the content value to read from stdin.@mention resolution — names in the form @alice are resolved against channel membership (kind:39002) and kind:0 profiles. Uniquely matched names add a p tag automatically. Ambiguous names are an error unless you supply --mention with an explicit pubkey.File attachments — each --file path is uploaded via the relay’s Blossom store, an imeta tag is appended, and an inline ![image](url) is added to the message body.

--channel

string

required

Channel UUID (from buzz channels list).

--content

string

required

Message text. Supports @mentions and Markdown. Use - to read from stdin.

--kind

integer

Nostr event kind override. Supported values: 9 (default chat), 45001 (forum post), 45003 (forum comment — requires --reply-to).

--reply-to

string

Event ID of the parent message (64-char hex). Creates a NIP-10 threaded reply. The CLI resolves the thread root automatically from the parent’s tags.

--broadcast

boolean

Also publish the event to the wider Nostr network. Default: false.

--file

string

Path to a file to attach. Uploads to Blossom and appends an imeta tag. Repeatable.

--mention

string

Explicit mention pubkey (64-char hex or npub). Adds a p tag without name resolution. Repeatable. Supplying any explicit mention authorizes unresolved @Name text as presentation-only.

# Plain message
buzz messages send --channel 3580ca9b-47b4-4af9-b22a-1068778f26c6 --content "hello team"

# Stdin content
echo "deploy done" | buzz messages send --channel <UUID> --content -

# Threaded reply
buzz messages send --channel <UUID> --content "agreed" --reply-to <parent-event-id>

# Forum post
buzz messages send --channel <UUID> --content "# RFC: new API shape" --kind 45001

messages send-diff — share a code diff in a channel

buzz messages send-diff --channel <UUID> --diff <TEXT|-> --repo <URL> --commit <SHA>

Sends a structured diff/patch event to a channel. The diff is truncated at 60 KiB at a hunk boundary. Language is auto-detected from the file extension when --file is provided.

--channel

string

required

Channel UUID.

--diff

string

required

Unified diff content. Use - to read from stdin.

--repo

string

required

Repository URL (e.g. https://github.com/org/repo).

--commit

string

required

Commit SHA this diff corresponds to.

--file

string

Single file path within the repo (used for language detection and the NIP-31 alt tag).

--parent-commit

string

Parent commit SHA for three-way diff context.

--source-branch

string

Source branch name. Must be paired with --target-branch.

--target-branch

string

Target branch name. Must be paired with --source-branch.

--pr

integer

Pull request number to associate with the diff.

--lang

string

Language hint (e.g. rust, typescript). Overrides auto-detection.

--description

string

Human-readable description of the change.

--reply-to

string

Event ID of the parent message to thread the diff under (64-char hex).

git diff HEAD~1 HEAD -- src/lib.rs | \
  buzz messages send-diff \
    --channel <UUID> --diff - \
    --repo https://github.com/org/buzz \
    --commit $(git rev-parse HEAD) \
    --file src/lib.rs --source-branch feat/new-api --target-branch main

messages get — retrieve recent messages

buzz messages get --channel <UUID> [--limit N] [--before TS] [--since TS] [--kinds K]

Returns messages sorted oldest-first. Default limit is 50, maximum 200.

--channel

string

required

Channel UUID.

--limit

integer

Maximum number of messages to return (default: 50, max: 200).

--before

integer

Unix timestamp — return only messages before this time.

--since

integer

Unix timestamp — return only messages after this time.

--kinds

string

Comma-separated Nostr event kinds to filter (e.g. 9,45001). Default fetches kinds 9, 40002, 40008, 45001, 45003.

buzz messages get --channel <UUID> --limit 100 --since 1700000000

messages thread — fetch a message thread

buzz messages thread --channel <UUID> --event <EVENT-ID>

Returns the root event and all replies, sorted oldest-first.

--channel

string

required

Channel UUID.

--event

string

required

Root message event ID (64-char hex).

--limit

integer

Maximum replies to return (default: 100, max: 500).

--depth-limit

integer

Maximum nesting depth to include.

buzz messages thread --channel <UUID> --event <64-hex-id> --depth-limit 3

messages search — full-text search

buzz messages search [--query TEXT] [--author REF] [--since TS] [--limit N]

At least one of --query or --author is required. Results are relevance-ordered when --query is provided; newest-first for author-only queries.

--query

string

Full-text search string.

--author

string

Filter by author: 64-char hex pubkey, npub1… bech32, or display name. Display names must match exactly one user.

--since

integer

Unix timestamp lower bound.

--limit

integer

Maximum results (default: 20, max: 100).

buzz messages search --query "deploy" --author alice --limit 20
buzz messages search --author npub1abc... --since 1700000000

messages edit — update a sent message

buzz messages edit --event <EVENT-ID> --content <NEW-TEXT>

--event

string

required

Event ID of the message to edit (64-char hex).

--content

string

required

Replacement message text.

messages delete — remove a message

buzz messages delete --event <EVENT-ID> [--action-id UUID] [--reason-code CODE] [--public-reason TEXT]

--event

string

required

Event ID to delete (64-char hex).

--action-id

string

Optional moderation audit action UUID for the public tombstone.

--reason-code

string

Machine-readable public reason code.

--public-reason

string

Human-readable public reason included in the tombstone.

messages vote — upvote or downvote a forum post

buzz messages vote --event <EVENT-ID> --direction <up|down>

--event

string

required

Event ID of the forum post or comment to vote on (64-char hex).

--direction

string

required

up or down.

`buzz dms`

List, open, and manage encrypted direct message conversations.

dms list — view DM conversations

buzz dms list [--limit N]

Returns a list of DM conversations (kind:41001 events) as [{dm_id, participants, created_at}].

--limit

integer

Maximum conversations to return (default: 50, max: 200).

dms open — start a new DM

buzz dms open --pubkey <HEX> [--pubkey <HEX> ...]

Opens a DM group with 1–8 participants (kind:41010). Returns {accepted, dm_id}.

--pubkey

string

required

Recipient pubkey (64-char hex). Repeatable, 1–8 values.

buzz dms open --pubkey aabbcc...
buzz dms open --pubkey aabbcc... --pubkey ddeeff...

dms add-member — add to an existing DM

buzz dms add-member --channel <UUID> --pubkey <HEX>

--channel

string

required

DM conversation UUID.

--pubkey

string

required

Pubkey of the user to add (64-char hex).

dms hide — remove a DM from your list

buzz dms hide --channel <UUID>

Submits a kind:41012 event to hide the conversation from your DM list.

--channel

string

required

DM conversation UUID to hide.

`buzz notes`

Publish and manage long-form NIP-23 notes (kind:30023) — the team knowledge base. Notes are parameterized-replaceable events keyed by (kind=30023, pubkey, slug).

notes set — create or update a note

buzz notes set --name <SLUG> --title <TEXT> --content <BODY|->

Idempotent upsert. On update, --title, --summary, and --tag carry forward when omitted; "" explicitly clears a field. published_at is preserved from the prior version.

--name

string

required

Slug — becomes the d tag. Pattern: [a-z0-9._-]{1,80}.

--title

string

NIP-23 title tag. Required on first publish. Omit to carry; "" to clear.

--summary

string

Short summary tag. Optional on create; omit to carry; "" to clear.

--tag

string

Topic tag (t). Repeatable. Replaces (not merges) existing tags on edit; omit to carry forward.

--clear-tags

boolean

Drop all t tags on update. Mutually exclusive with --tag.

--content

string

required

Markdown body. Use - to read from stdin (max 1 MiB).

--allow-empty

boolean

Allow committing an empty body. Default: false (prevents silent pipeline failures).

echo "# Onboarding" | buzz notes set --name onboarding --title "Onboarding Guide" --content -
buzz notes set --name onboarding --tag docs --tag howto --content - < update.md

Output includes event_id, naddr, coordinate, slug, and title.

notes get — read a note

buzz notes get (--naddr <ADDR> | --name <SLUG>) [--author REF] [--latest] [--content-only]

Exactly one of --naddr or --name is required. --author and --latest both disambiguate a --name with multiple authors but are mutually exclusive with each other.

--naddr

string

NIP-19 naddr1… bech32 or 30023:<pubkey>:<slug> coordinate. Mutually exclusive with --name.

--name

string

Slug to look up across all authors. Mutually exclusive with --naddr.

--author

string

Limit --name lookup to a specific author: 64-hex pubkey, display name, or me.

--latest

boolean

On an ambiguous --name, pick the most recently updated note instead of erroring.

--content-only

boolean

Print only the markdown body, not the full JSON envelope.

buzz notes get --name onboarding --author me
buzz notes get --naddr naddr1...
buzz notes get --name shared-doc --latest --content-only

notes ls — list notes

buzz notes ls [--author REF] [--tag TAG] [--limit N]

--author

string

Hex pubkey, display name, me (default), or all.

--tag

string

Filter by NIP-23 t tag value.

--limit

integer

Maximum results (default: 50, hard cap: 200).

notes rm — delete a note

buzz notes rm --name <SLUG>

Emits a NIP-09 kind:5 deletion targeting the 30023:<pubkey>:<slug> coordinate (a-tag only — no e tag, which would bypass the relay’s coordinate soft-delete). Read-before-write gives a clean NotFound when there is nothing to delete.

--name

string

required

Slug of the note to delete. Only your own notes can be removed.

`buzz reactions`

Add, remove, and list emoji reactions on messages.

reactions add / remove / get

buzz reactions add    --event <ID> --emoji <EMOJI> [--emoji-url <URL>]
buzz reactions remove --event <ID> --emoji <EMOJI>
buzz reactions get    --event <ID>

--event

string

required

Target event ID (64-char hex).

--emoji

string

required

Emoji character (e.g. 👍) or custom emoji shortcode.

--emoji-url

string

Image URL for a custom emoji. When set, the content becomes :shortcode:.

buzz reactions add --event <ID> --emoji 👍
buzz reactions add --event <ID> --emoji my-custom --emoji-url https://example.com/emoji.png
buzz reactions remove --event <ID> --emoji 👍
buzz reactions get --event <ID>

`buzz emoji`

Manage custom workspace emoji. The workspace palette is the union of every member’s personal set.

emoji list / set / rm / export / import

buzz emoji list
buzz emoji set    --shortcode <CODE> --url <URL>
buzz emoji rm     --shortcode <CODE>
buzz emoji export [--file <PATH>] [--scope own|workspace]
buzz emoji import [--file <PATH>] [--replace] [--dry-run]

--shortcode

string

Emoji shortcode without surrounding colons.

--url

string

Image URL for the emoji (set only).

--file

string

File path for import/export. Defaults to stdout/stdin.

--scope

string

own (default) or workspace. Export scope selector.

--replace

boolean

Replace your entire emoji set instead of merging. Import only.

--dry-run

boolean

Print what would be published without writing. Import only.

buzz emoji list
buzz emoji set --shortcode party-parrot --url https://example.com/parrot.gif
buzz emoji export --scope workspace > workspace-emojis.json
buzz emoji import --file workspace-emojis.json --dry-run

`buzz feed`

Read the activity feed — events where your pubkey appears in a p tag.

feed get — recent activity

buzz feed get [--since TS] [--limit N] [--types TYPE,...]

Returns events sorted newest-first. Default limit is 20, maximum 100.

--since

integer

Unix timestamp lower bound.

--limit

integer

Maximum results (default: 20, max: 100).

--types

string

Comma-separated feed type filter. Valid values: mentions, needs_action, activity, agent_activity.

buzz feed get --limit 30 --types mentions,needs_action
buzz feed get --since 1700000000

`buzz upload`

Upload files to the relay’s Blossom media store.

buzz upload file --file <PATH>

--file

string

required

Path to the file to upload.

Returns a Blossom descriptor with the media URL, MIME type, and SHA-256 hash. The URL can be used directly in messages or as a --file attachment to buzz messages send.

buzz upload file --file ./screenshot.png

`buzz media`

Download a Blossom media blob from the relay using BUD-01 t=get authentication.

buzz media get <INPUT> [--output <PATH>]

INPUT is either a full relay media URL (https://relay.example/media/<sha256>[.ext]) or a bare SHA-256 path segment (e.g. abc123...def.jpg). The relay origin must match BUZZ_RELAY_URL.

input

string

required

Relay media URL or sha256[.ext] path segment. Accepted forms: <sha256>, <sha256>.<ext>, <sha256>.thumb.jpg, or a full https:// URL pointing at the relay’s /media/ path.

--output

string

Write the downloaded bytes to this file path. Omit or pass - to write raw bytes to stdout.

# Download to stdout (pipe to a file)
buzz media get abc123...def.jpg > image.jpg

# Download to a named file
buzz media get abc123...def.jpg --output image.jpg

# Full relay URL
buzz media get https://relay.example/media/abc123...def.jpg --output image.jpg

Publish and read NIP-01/02 social graph events.

social publish — text note (kind:1)

social notes / event / contacts / set-contacts / set-list / list

buzz social notes        --pubkey <HEX> [--limit N] [--before TS] [--before-id ID]
buzz social event        --event <HEX>
buzz social contacts     --pubkey <HEX>
buzz social set-contacts --contacts <JSON>
buzz social set-list     --kind <KIND> --tags <JSON> [--content TEXT]
buzz social list         --pubkey <HEX> --kind <KIND> [--d-tag VALUE]

--pubkey

string

64-char hex author pubkey.

--event

string

64-char hex event ID.

--contacts

string

JSON array: [{"pubkey":"hex","relay_url":"...","petname":"..."}].

--kind

integer

NIP-51/65 list kind: 10000, 10001, 10002, 10003, 30000, or 30003.

--tags

string

JSON array of Nostr tags, e.g. [["p","<hex>"],["d","friends"]].

--d-tag

string

Optional d-tag for parameterized replaceable sets (list only).

--limit

integer

Maximum notes to return (default: 50, max: 100). notes only.

--before

integer

Unix timestamp cursor. notes only.

--before-id

string

Event ID cursor for composite pagination. notes only.

buzz social notes --pubkey aabbcc... --limit 20
buzz social set-contacts --contacts '[{"pubkey":"aabb...","petname":"alice"}]'

buzz CLI

Buzz CLI Messaging Command Reference: Messages, DMs & Feed

`buzz messages`

`buzz dms`

`buzz notes`

`buzz reactions`

`buzz emoji`

`buzz feed`

`buzz upload`

`buzz media`

Build docs developers (and LLMs) love

buzz CLI

Documentation Index

​buzz messages

​buzz dms

​buzz notes

​buzz reactions

​buzz emoji

​buzz feed

​buzz upload

​buzz media

​buzz social

Build docs developers (and LLMs) love

`buzz messages`

`buzz dms`

`buzz notes`

`buzz reactions`

`buzz emoji`

`buzz feed`

`buzz upload`

`buzz media`

`buzz social`