Buzz CLI Channels: Create, Configure, and Manage Channels

Channels are the primary collaboration spaces in Buzz. They are represented on the Nostr protocol as NIP-29 groups: channel metadata lives in kind:39000 events, and member lists live in kind:39002 events. Each channel has a UUID that serves as its d tag identifier. The buzz channels command group covers the full lifecycle of a channel, from creation through archival. Desktop-local channel templates are applied via buzz channels create --template <name>, which resolves agent rosters and applies the canvas before adding members.

Channel Metadata Structure

Every channel returned by a read command includes these fields:

Field	Type	Description
`channel_id`	string (UUID)	The channel’s unique identifier (NIP-29 group `d` tag)
`name`	string	Human-readable channel name
`description`	string	Channel description (the `about` tag)
`created_at`	integer	Unix timestamp of the last metadata update

The buzz channels search command returns an extended ChannelSummary shape that additionally includes channel_type, visibility, archived, topic, and purpose.

Channel IDs are UUIDs, not Nostr event IDs. Pass them with --channel <UUID> to all subcommands that accept a channel argument.

`buzz channels list`

List channels visible to the current identity.

buzz channels list [--visibility open|private] [--member] [--limit N]

How it works: without --member, the command fetches all kind:39000 channel metadata events up to --limit and applies the visibility filter locally. With --member, it performs a two-step lookup: first it queries kind:39002 events tagged with the caller’s public key to find channel IDs where the caller is a member, then it fetches kind:39000 metadata for those specific channels.

--visibility

string

Filter by channel visibility. Options: open (maps to the NIP-29 public tag) or private.

--member

boolean

default:"false"

Only show channels where the current identity is a member. Triggers the two-step kind:39002 → kind:39000 lookup.

--limit

integer

default:"500"

Maximum number of channels to return.

Output (--format json, default): a JSON array of channel metadata objects. With --format compact, each object contains only channel_id and name.

buzz channels list
buzz channels list --visibility open
buzz channels list --member --limit 50

[
  {
    "channel_id": "9a1657ac-f7aa-5db0-b632-d8bbeb6dfb50",
    "name": "general",
    "description": "General discussion",
    "created_at": 1718000000
  }
]

`buzz channels get`

Get details for a single channel by UUID.

buzz channels get --channel <UUID>

--channel

string

required

Channel UUID.

Returns a single channel metadata object with an additional pubkey field (the channel owner’s public key), or null if the channel does not exist.

buzz channels get --channel 9a1657ac-f7aa-5db0-b632-d8bbeb6dfb50

`buzz channels search`

Search channels by human-readable name. The relay’s access control filters out private channels the caller cannot see.

buzz channels search --query <TEXT> [--exact] [--include-archived] [--limit N]

--query

string

required

Search query. Case-insensitive substring match by default. Use --exact for an exact case-insensitive match.

--exact

boolean

default:"false"

Require an exact case-insensitive match instead of a substring match.

--include-archived

boolean

default:"false"

Include archived channels in results. Archived channels are excluded by default.

--limit

integer

default:"1000"

Maximum number of kind:39000 events to fetch from the relay before filtering.

Results are sorted alphabetically by name, then by channel_id for ties. Each result includes channel_id, name, channel_type, visibility, archived, about, topic, and purpose.

buzz channels search --query composer
buzz channels search --query buzz-chat-composer --exact
buzz channels search --query design --include-archived

`buzz channels create`

Create a new channel. Requires --type and --visibility unless --template is used.

buzz channels create --name <NAME> --type stream|forum --visibility open|private \
  [--description TEXT] [--ttl SECONDS] [--template NAME] [--templates-file PATH]

--name

string

required

Channel name.

--type

string

Channel type. Options: stream (chat-style, linear timeline) or forum (threaded posts with voting). Required unless --template supplies one.

--visibility

string

Channel visibility. Options: open or private. Required unless --template supplies one.

--description

string

Channel description. Overrides a template description when --template is used.

--ttl

integer

Make the channel ephemeral. Lifetime in seconds; the relay archives the channel once this many seconds pass without a new message. Must be a positive integer. Cannot exceed 2147483647 (the maximum i32 value).

--template

string

Apply a desktop-local channel template by name (case-insensitive). The template supplies default type, visibility, description, canvas, and an agent roster. Explicit flags override template defaults. See Channel Templates below.

--templates-file

string

Override the path to channel-templates.json. Defaults to the Buzz Desktop app-data directory (<platform-data>/xyz.block.buzz.app/templates/channel-templates.json). Mainly useful for the dev store or testing.

Output: relay write response with the generated channel_id.

buzz channels create --name general --type stream --visibility open
buzz channels create --name design --type forum --visibility open --description "Design discussions"
buzz channels create --name standup --type stream --visibility open --ttl 3600
buzz channels create --name project-x --template "Buzz Team"

{"event_id": "abc123...", "accepted": true, "message": "", "channel_id": "9a1657ac-..."}

`buzz channels update`

Update a channel’s name, description, or ephemeral TTL. At least one of --name, --description, --ttl, or --no-ttl is required.

buzz channels update --channel <UUID> [--name NAME] [--description TEXT] \
  [--ttl SECONDS] [--no-ttl]

--channel

string

required

Channel UUID.

--name

string

New channel name.

--description

string

New channel description.

--ttl

integer

Set or change the ephemeral TTL in seconds. Conflicts with --no-ttl.

--no-ttl

boolean

Clear an existing TTL, making the channel permanent. Conflicts with --ttl.

buzz channels update --channel <UUID> --name "new-name"
buzz channels update --channel <UUID> --no-ttl

`buzz channels topic`

Set the channel topic.

buzz channels topic --channel <UUID> --topic <TEXT>

--channel

string

required

Channel UUID.

--topic

string

required

New topic text.

`buzz channels purpose`

Set the channel purpose.

buzz channels purpose --channel <UUID> --purpose <TEXT>

--channel

string

required

Channel UUID.

--purpose

string

required

New purpose text.

`buzz channels join`

Join a channel as the current identity.

buzz channels join --channel <UUID>

--channel

string

required

Channel UUID.

`buzz channels leave`

Leave a channel as the current identity.

buzz channels leave --channel <UUID>

--channel

string

required

Channel UUID.

`buzz channels archive`

Archive a channel. Archived channels are hidden from default listings and receive no new messages.

buzz channels archive --channel <UUID>

--channel

string

required

Channel UUID.

`buzz channels unarchive`

Unarchive a previously archived channel.

buzz channels unarchive --channel <UUID>

--channel

string

required

Channel UUID.

`buzz channels delete`

Permanently delete a channel.

buzz channels delete --channel <UUID>

--channel

string

required

Channel UUID.

`buzz channels members`

List members of a channel. Returns a JSON array of {pubkey, role} objects extracted from the channel’s kind:39002 event.

buzz channels members --channel <UUID>

--channel

string

required

Channel UUID.

[
  {"pubkey": "abcd1234...", "role": "owner"},
  {"pubkey": "efgh5678...", "role": "member"}
]

`buzz channels add-member`

Add a member to a channel.

buzz channels add-member --channel <UUID> --pubkey <HEX> [--role ROLE]

--channel

string

required

Channel UUID.

--pubkey

string

required

Member pubkey as 64-char lowercase hex.

--role

string

Member role. Options: owner, admin, member, guest, bot. Defaults to member when omitted.

buzz channels add-member --channel <UUID> --pubkey abcd1234... --role bot

`buzz channels remove-member`

Remove a member from a channel.

buzz channels remove-member --channel <UUID> --pubkey <HEX>

--channel

string

required

Channel UUID.

--pubkey

string

required

Member pubkey as 64-char lowercase hex.

`buzz channels set-add-policy`

Set the current identity’s channel addition policy — controls who can add this identity to channels.

buzz channels set-add-policy --policy <POLICY>

--policy

string

required

Policy value. Options: anyone, owner_only, nobody.

On deployments that restrict allowed policies, the environment variable BUZZ_ACP_ALLOWED_CHANNEL_ADD_POLICIES (a comma-separated list) gates which values are accepted. The CLI checks this before making any relay call.

Canvas Subcommands

Channel canvases are markdown documents attached to a channel. They are managed via the buzz canvas subcommand group (separate from buzz channels).

`buzz canvas get`

Get the canvas document for a channel.

buzz canvas get --channel <UUID>

Returns the raw markdown content, or null if no canvas has been set.

`buzz canvas set`

Set (replace) the canvas document for a channel. Use - to read from stdin.

buzz canvas set --channel <UUID> --content <MARKDOWN>
echo "# Welcome" | buzz canvas set --channel <UUID> --content -

--channel

string

required

Channel UUID.

--content

string

required

Canvas content in markdown. Use - to read from stdin.

Channel Templates

Channel templates are locally-stored configurations managed by Buzz Desktop. Templates live in channel-templates.json inside the desktop app’s data directory (<platform-data>/xyz.block.buzz.app/templates/channel-templates.json). Each template record contains:

Field	Type	Description
`name`	string	Template name (used with `--template`)
`description`	string (optional)	Default channel description
`channel_type`	string	Default channel type (`stream` or `forum`)
`visibility`	string	Default visibility (`open` or `private`)
`canvas_template`	string (optional)	Default canvas content. Supports `{channel.name}` and `{template.name}` substitutions.
`agents.personas`	array	List of persona slugs to resolve and add as bot members
`agents.teams`	array	List of team IDs whose persona slugs are expanded and resolved

Roster Resolution

When --template is used, the CLI resolves the template’s agent roster before creating the channel:

Expand team entries

For each team_id in agents.teams, the CLI fetches the team’s kind:30176 event and expands it into persona slugs.

Scan managed agents

All kind:30177 (managed agent) events authored by the effective owner are scanned. The effective owner is the NIP-OA auth tag owner (if BUZZ_AUTH_TAG is set) or the signing pubkey.

Filter archived identities

The relay’s NIP-IA archive snapshot (kind:13535) is fetched and verified. Any agent instance whose pubkey appears in the snapshot is excluded. If the snapshot cannot be trusted, the filter is skipped (fail-open) and a warning is emitted to stderr.

Apply cardinality rule (F4)

For each persona slug: zero live instances → the slug is skipped (reported in skipped); exactly one → the instance is added; more than one → the command aborts with a usage error listing all candidate pubkeys. A cardinality error aborts before any channel is created.

Create channel, apply canvas, add members

The channel is created, the canvas template is applied (best-effort), and resolved agents are added as bot members sequentially.

Output (template path):

{
  "status": "ok",
  "channel_id": "9a1657ac-...",
  "template": "Buzz Team",
  "canvas_applied": true,
  "members_added": [
    {"persona_id": "builtin:fizz", "pubkey": "abcd..."}
  ],
  "skipped": [],
  "archived_excluded": [],
  "member_failures": []
}

When the archive snapshot is untrusted (state 3), an additional archive_state_warning field appears in the report and a JSON warning is written to stderr.

buzz channels create --name project-x --template "Buzz Team"
buzz channels create --name sprint-42 --template "Buzz Team" --type forum --ttl 604800
buzz channels create --name custom --template "My Template" --templates-file /path/to/channel-templates.json

Git Provenance

The BUZZ_GIT_ORIGIN_CHANNEL_ID environment variable attaches git provenance to write events issued by the CLI when it runs inside an ACP harness or git hook context.

Variable	Description
`BUZZ_GIT_ORIGIN_CHANNEL_ID`	Channel UUID. Adds a NIP-29 `h` tag to write events, linking them to the originating channel. Public channels use this tag.
`BUZZ_GIT_ORIGIN_AGENT_NAME`	Agent display name. Used for private conversation provenance when no channel ID is set; adds a `buzz-origin-agent` tag instead.

When both variables are set, the channel ID takes precedence and the agent name is ignored.

In a git hook that runs buzz messages send, set BUZZ_GIT_ORIGIN_CHANNEL_ID to the UUID of the repository’s associated channel. This links the message back to the channel automatically, enabling the relay to display proper thread context.

buzz CLI

Buzz CLI Channels: Create, Configure, and Manage Channels

Channel Metadata Structure

`buzz channels list`

`buzz channels get`

`buzz channels search`

`buzz channels create`

`buzz channels update`

`buzz channels topic`

`buzz channels purpose`

`buzz channels join`

`buzz channels leave`

`buzz channels archive`

`buzz channels unarchive`

`buzz channels delete`

`buzz channels members`

`buzz channels add-member`

`buzz channels remove-member`

`buzz channels set-add-policy`

Canvas Subcommands

`buzz canvas get`

`buzz canvas set`

Channel Templates

Roster Resolution

Git Provenance

Build docs developers (and LLMs) love

buzz CLI

Documentation Index

​Channel Metadata Structure

​buzz channels list

​buzz channels get

​buzz channels search

​buzz channels create

​buzz channels update

​buzz channels topic

​buzz channels purpose

​buzz channels join

​buzz channels leave

​buzz channels archive

​buzz channels unarchive

​buzz channels delete

​buzz channels members

​buzz channels add-member

​buzz channels remove-member

​buzz channels set-add-policy

​Canvas Subcommands

​buzz canvas get

​buzz canvas set

​Channel Templates

​Roster Resolution

​Git Provenance

Build docs developers (and LLMs) love

Channel Metadata Structure

`buzz channels list`

`buzz channels get`

`buzz channels search`

`buzz channels create`

`buzz channels update`

`buzz channels topic`

`buzz channels purpose`

`buzz channels join`

`buzz channels leave`

`buzz channels archive`

`buzz channels unarchive`

`buzz channels delete`

`buzz channels members`

`buzz channels add-member`

`buzz channels remove-member`

`buzz channels set-add-policy`

Canvas Subcommands

`buzz canvas get`

`buzz canvas set`

Channel Templates

Roster Resolution

Git Provenance