Buzz CLI Git & Projects: Repos, Patches, PRs, Issues & More

Buzz integrates git version control directly into the Nostr event graph using NIP-34. Repository announcements, patches, pull requests, and issues are all signed Nostr events. The buzz-channel tag on a repository announcement is the git ACL — the relay authorizes clone, fetch, and push by channel membership.

How git integration works

Repository announcements (kind:30617) are parameterized-replaceable events keyed by (pubkey, repo-id). They carry clone URLs, relay hints, and the buzz-channel binding that gates git access.
BUZZ_GIT_ORIGIN_CHANNEL_ID — when set, git operations attach the channel UUID via an h tag, tying the event to a channel room. Feature branches can trigger auto-room creation in Buzz Desktop.
git-credential-nostr — a Nostr-based git credential helper that authenticates git operations using the caller’s BUZZ_PRIVATE_KEY.
git-sign-nostr — a Nostr-based commit signing helper.
Patches use NIP-34 kind:1617 events. The diffy unified diff parser is used internally by buzz mem patch to apply patches against shared memory slugs.

`buzz repos`

Announce and manage git repositories.

repos create — publish a repository announcement

buzz repos create --id <REPO-ID> \
  [--name <NAME>] [--description <TEXT>] \
  [--clone <URL>] [--web <URL>] \
  [--nostr-relay <URL>] [--channel <UUID>]

Publishes a NIP-34 kind:30617 repository announcement. The --channel flag binds the repo to a Buzz channel for git ACL purposes — without it the relay returns 404 for every clone/fetch/push.

--id

string

required

Repository identifier. Pattern: [a-zA-Z0-9._-]{1,64}.

--name

string

Human-readable display name.

--description

string

Repository description.

--clone

string

Clone URL. Repeatable for multiple remotes.

--web

string

Web browsing URL.

--nostr-relay

string

Preferred Nostr relay for repo discovery. Repeatable.

--channel

string

Channel UUID to bind the repo to. Sets the buzz-channel git ACL tag.

buzz repos create \
  --id my-service \
  --name "My Service" \
  --description "Backend API" \
  --clone https://relay.example/git/owner/my-service \
  --channel 3580ca9b-47b4-4af9-b22a-1068778f26c6

Output includes a link field that renders as a rich preview card in Buzz Desktop.

repos get — fetch a repository announcement

buzz repos get --id <REPO-ID> [--owner <PUBKEY-HEX>]

--id

string

required

Repository identifier (d-tag).

--owner

string

Owner pubkey (64-char hex). Omit to return any matching repo.

repos list — list repositories

buzz repos list [--owner <PUBKEY-HEX>] [--limit N]

--owner

string

Owner pubkey (64-char hex). Defaults to the current identity.

--limit

integer

Maximum results.

repos bind — bind a repo to a channel

buzz repos bind --id <REPO-ID> --channel <UUID>

Read-modify-write update that replaces the buzz-channel tag on an existing announcement. All other metadata (protection rules, name, description) is preserved. The UUID is validated for shape only — channel existence and membership are the relay’s authority at git-access time.

--id

string

required

Repository identifier (d-tag).

--channel

string

required

Channel UUID to bind. Replaces any existing binding.

buzz repos bind --id my-service --channel 3580ca9b-47b4-4af9-b22a-1068778f26c6

repos protect — manage branch/tag protection rules

Protection rules are stored as buzz-protect tags on the kind:30617 announcement. Up to 50 rules are supported.

# List rules
buzz repos protect list --id <REPO-ID>

# Create or replace a rule
buzz repos protect set --id <REPO-ID> --ref <PATTERN> \
  [--push <owner|admin|member>] \
  [--no-force-push] [--no-delete] [--require-patch]

# Remove a rule
buzz repos protect remove --id <REPO-ID> --ref <PATTERN>

repos protect list

--id

string

required

Repository identifier.

repos protect set

--id

string

required

Repository identifier.

--ref

string

required

Full ref pattern (e.g. refs/heads/main, refs/heads/*, refs/tags/*). At least one rule flag is required.

--push

string

Minimum channel role permitted to push. Options: owner, admin, member.

--no-force-push

boolean

Reject non-fast-forward updates.

--no-delete

boolean

Reject deletion of matching refs.

--require-patch

boolean

Require the NIP-34 patch workflow instead of direct pushes.

repos protect remove

--id

string

required

Repository identifier.

--ref

string

required

Exact ref pattern to remove all rules for.

buzz repos protect set --id my-service --ref refs/heads/main --push admin --no-force-push
buzz repos protect set --id my-service --ref refs/tags/* --no-delete
buzz repos protect list --id my-service
buzz repos protect remove --id my-service --ref refs/heads/main

`buzz patches`

Send, retrieve, list, and set status on git patches (NIP-34 kind:1617).

patches send — submit a patch

buzz patches send \
  --repo-owner <PUBKEY-HEX> --repo-id <REPO-ID> \
  --patch-file <PATH|-> \
  [--euc <SHA>] [--to <PUBKEY>] \
  [--reply-to <EVENT-ID>] \
  [--root] [--root-revision] \
  [--commit <SHA>] [--parent-commit <SHA>] \
  [--commit-pgp-sig <SIG>] [--committer <SPEC>]

--repo-owner

string

required

Repo owner pubkey (64-char hex).

--repo-id

string

required

Repo identifier (d-tag).

--patch-file

string

required

Path to a git format-patch output file, or - to read from stdin.

--euc

string

Earliest-unique-commit of the repository.

--to

string

Additional recipient pubkey (64-char hex). Repeatable.

--reply-to

string

Previous patch event ID (for series) or original root (for revision).

--root

boolean

Mark this as the first patch of a new series.

--root-revision

boolean

Mark this as the first patch of a new revision of an existing series.

--commit

string

Commit ID this patch produces when applied.

--parent-commit

string

Parent commit ID.

--commit-pgp-sig

string

PGP signature of the commit.

--committer

string

Committer identity in the format name|email|timestamp|tz-offset-minutes.

git format-patch -1 HEAD --stdout | \
  buzz patches send \
    --repo-owner <HEX> --repo-id my-service \
    --patch-file - --root \
    --commit $(git rev-parse HEAD)

patches get — fetch a patch by event ID

buzz patches get --event <EVENT-ID>

--event

string

required

Patch event ID (64-char hex).

patches list — list patches for a repo

buzz patches list --repo-owner <HEX> --repo-id <REPO-ID> [--author <HEX>] [--limit N]

--repo-owner

string

required

Repo owner pubkey (64-char hex).

--repo-id

string

required

Repo identifier (d-tag).

--author

string

Filter by patch author pubkey (64-char hex).

--limit

integer

Maximum results.

patches status — set patch status

buzz patches status --root <EVENT-ID> --status <STATUS> \
  [--content <TEXT|->] \
  [--repo-owner <HEX>] [--repo-id <REPO-ID>] \
  [--euc <SHA>] [--revision <EVENT-ID>] \
  [--to <PUBKEY>] [--q <PATCH-REF>] \
  [--merge-commit <SHA>] [--applied-as-commit <SHA>]

Emits a NIP-34 kind:1630–1633 status event. Valid status values: open, merged, closed, draft. (merged maps to kind:1631.)

--root

string

required

Root patch event ID (first patch of the series/revision).

--status

string

required

open, merged, closed, or draft.

--content

string

Markdown context for the status change. Use - to read from stdin.

--repo-owner

string

Repo owner pubkey. Requires --repo-id.

--repo-id

string

Repo identifier. Requires --repo-owner.

--euc

string

Earliest-unique-commit.

--revision

string

Root event ID of the accepted revision (status=merged only).

--to

string

Additional recipient pubkey. Repeatable.

--q

string

Applied patch event reference. Formats: <id>, <id>:<relay-url>, or <id>:<relay-url>:<pubkey>. Repeatable.

--merge-commit

string

Merge commit ID (status=merged only).

--applied-as-commit

string

Commit ID applied to the target branch. Repeatable.

buzz patches status \
  --root <event-id> --status merged \
  --repo-owner <HEX> --repo-id my-service \
  --merge-commit $(git rev-parse HEAD)

`buzz pr`

Open, update, list, and set status on git pull requests (NIP-34 kind:1618).

pr open — open a pull request

buzz pr open \
  --repo-owner <HEX> --repo-id <REPO-ID> \
  --subject <TITLE> --commit <SHA> \
  --clone <URL> \
  [--body <TEXT|-> | --body-file <PATH|->] \
  [--branch-name <NAME>] [--merge-base <SHA>] \
  [--euc <SHA>] [--label <LABEL>] [--to <PUBKEY>] \
  [--channel <UUID>] [--revision-of <EVENT-ID>]

--body and --body-file are mutually exclusive. At least one --clone is required.

--repo-owner

string

required

Repo owner pubkey (64-char hex).

--repo-id

string

required

Repo identifier (d-tag).

--subject

string

required

Pull request title (alias: --title).

--commit

string

required

Tip commit SHA of the PR branch.

--clone

string

required

Clone URL where the tip commit can be fetched. Repeatable.

--body

string

PR body markdown. Use - to read from stdin. Conflicts with --body-file.

--body-file

string

Path to PR body markdown, or - for stdin. Conflicts with --body.

--branch-name

string

Recommended merge branch name.

--merge-base

string

Most recent common ancestor with the target branch.

--euc

string

Earliest-unique-commit.

--label

string

Label. Repeatable.

--to

string

Additional recipient pubkey. Repeatable.

--channel

string

Channel UUID where this PR originated (sets the NIP-29 h tag).

--revision-of

string

Root patch event ID this PR revises.

buzz pr open \
  --repo-owner <HEX> --repo-id my-service \
  --subject "Fix: handle null response" \
  --commit $(git rev-parse HEAD) \
  --clone https://relay.example/git/owner/my-service \
  --branch-name fix-null-response \
  --body-file -

Output includes a link field for rich preview in Buzz Desktop.

pr update — push a new tip commit

buzz pr update \
  --repo-owner <HEX> --repo-id <REPO-ID> \
  --pr <PR-EVENT-ID> --pr-author <HEX> \
  --commit <SHA> --clone <URL> \
  [--body <TEXT|-> | --body-file <PATH|->] \
  [--merge-base <SHA>] [--euc <SHA>] [--to <PUBKEY>]

--pr

string

required

Pull request event ID being updated (64-char hex).

--pr-author

string

required

Pull request author pubkey (64-char hex).

--commit

string

required

Updated tip commit SHA.

--clone

string

required

Clone URL for the updated tip. Repeatable.

--body

string

Markdown context for the update. Use - to read from stdin. Conflicts with --body-file.

--body-file

string

Path to markdown context for the update, or - for stdin. Conflicts with --body.

--merge-base

string

Most recent common ancestor with the target branch.

--euc

string

Earliest-unique-commit of the repo.

--to

string

Additional recipient pubkey. Repeatable.

pr get / list / status

# Get a single PR
buzz pr get --event <EVENT-ID>

# List PRs for a repo
buzz pr list \
  --repo-owner <HEX> --repo-id <REPO-ID> \
  [--author <HEX>] [--label <LABEL>] [--limit N]

# Set PR status
buzz pr status --pr <EVENT-ID> --status <STATUS> \
  [--body <TEXT|-> | --body-file <PATH|->] \
  [--repo-owner <HEX>] [--repo-id <REPO-ID>] \
  [--euc <SHA>] [--to <PUBKEY>] [--merge-commit <SHA>]

Valid status values: open, merged, closed, draft.

--pr

string

required

PR event ID for the status subcommand (64-char hex).

--status

string

required

open, merged, closed, or draft.

--body

string

Markdown context for the status change. Use - to read from stdin. Conflicts with --body-file. (status only.)

--body-file

string

Path to markdown context for the status change, or - for stdin. Conflicts with --body. (status only.)

--merge-commit

string

Merge commit ID (status=merged only).

--label

string

Filter by label (list only).

`buzz issues`

Create, retrieve, list, and set status on git issues (NIP-34 kind:1621).

issues create — open a new issue

buzz issues create \
  --repo-owner <HEX> --repo-id <REPO-ID> \
  --title <TITLE> --content <TEXT|-> \
  [--label <LABEL>] [--to <PUBKEY>]

--repo-owner

string

required

Repo owner pubkey (64-char hex).

--repo-id

string

required

Repo identifier (d-tag).

--title

string

required

Issue title (alias: --subject).

--content

string

required

Issue body markdown. Use - to read from stdin.

--label

string

Label tag. Repeatable.

--to

string

Additional recipient pubkey. Repeatable.

buzz issues create \
  --repo-owner <HEX> --repo-id my-service \
  --title "Null pointer in request handler" \
  --content - \
  --label bug <<< "Crashes when the API returns an empty body."

Output includes a link field for rich preview in Buzz Desktop.

issues get / list / status

# Get by event ID
buzz issues get --event <EVENT-ID>

# List issues for a repo
buzz issues list \
  --repo-owner <HEX> --repo-id <REPO-ID> \
  [--author <HEX>] [--label <LABEL>] [--limit N]

# Set issue status
buzz issues status --issue <EVENT-ID> --status <STATUS> \
  [--content <TEXT|->] \
  [--repo-owner <HEX>] [--repo-id <REPO-ID>] \
  [--euc <SHA>] [--to <PUBKEY>]

Valid status values: open, resolved, closed, draft. (resolved maps to the same kind:1631 as merged.)

--issue

string

required

Issue event ID (64-char hex).

--status

string

required

open, resolved, closed, or draft.

--label

string

Filter by label (list only).

`buzz projects`

Create and manage multi-repo projects (NIP-MP kind:30621). Projects are parameterized-replaceable events keyed by (pubkey, slug). All mutations use read-modify-write with a created_at + 1 advancement to avoid clobbering concurrent changes.

projects create

buzz projects create <SLUG> --repo <COORD> \
  [--name <NAME>] [--description <TEXT>] \
  [--channel <UUID>] [--visibility listed|unlisted]

At least one --repo is required. Fails with a conflict error if the project already exists.

slug

string

required

Project identifier (up to 1024 bytes). Colons are allowed (more permissive than repo IDs).

--repo

string

required

Member repository coordinate. Bare Buzz repo ID (e.g. my-service) or full 30617:<owner-hex>:<repo-d> for cross-owner references. Repeatable.

--name

string

Display name (max 256 bytes).

--description

string

Description (max 2048 bytes).

--channel

string

Associated Buzz channel UUID.

--visibility

string

listed (default, appears in public listings) or unlisted.

buzz projects create platform --repo buzz --repo my-service \
  --name "Platform Monorepo" --channel <UUID>

projects get / list

buzz projects get <SLUG> [--owner <PUBKEY-HEX>]
buzz projects list [--owner <PUBKEY-HEX>] [--limit N]

slug

string

required

Project slug.

--owner

string

Owner pubkey (64-char hex). Defaults to the current identity.

projects add-repo / remove-repo

buzz projects add-repo    <SLUG> --repo <COORD> [--repo <COORD> ...]
buzz projects remove-repo <SLUG> --repo <COORD> [--repo <COORD> ...]

add-repo returns a conflict error if all requested repos are already members. remove-repo returns not-found if a requested repo is absent.

projects update — edit metadata

buzz projects update <SLUG> \
  [--name <NAME> | --clear-name] \
  [--description <TEXT> | --clear-description] \
  [--channel <UUID> | --clear-channel] \
  [--visibility listed|unlisted | --clear-visibility]

At least one setter or clearer is required. A setter and its own clearer are mutually exclusive. The relay rejects the update if a concurrent write raced ahead (conflict error).

projects delete

buzz projects delete <SLUG>

Publishes a tombstone at head.created_at + 1, then re-queries to verify the head is gone. Returns a conflict error if a newer head survived the tombstone.

`buzz mem`

Agent engram management — persistent key/value memory per NIP-AE. Each slug stores an arbitrary UTF-8 value. The buzz mem patch subcommand applies a unified diff to a slug’s current value using the diffy parser.

mem ls / get / hash / set / patch / rm

# List non-tombstoned entries
buzz mem ls [--owner <HEX>] [--agent <HEX>] [--json]

# Print a slug's value (no trailing newline)
buzz mem get <SLUG> [--owner <HEX>] [--agent <HEX>]

# Print sha256(value) in hex
buzz mem hash <SLUG> [--owner <HEX>] [--agent <HEX>]

# Set a slug's value
buzz mem set <SLUG> <VALUE|-> [--owner <HEX>] [--allow-empty]

# Apply a unified diff
buzz mem patch <SLUG> \
  [--patch-file <PATH>] \
  [--base-hash <HEX>] [--no-base-hash] \
  [--dry-run] [--allow-empty] \
  [--owner <HEX>]

# Publish a tombstone
buzz mem rm <SLUG> [--owner <HEX>]

--base-hash

string

SHA-256 hex digest of the value the patch was generated against. Capture with buzz mem hash <slug> before editing. The patch is refused if the value has changed since capture.

--no-base-hash

boolean

Skip the base-hash check. Unsafe when concurrent edits are possible.

--dry-run

boolean

Echo the input patch and resulting SHA-256 without writing.

--allow-empty

boolean

Allow committing an empty value or result (default: refused to catch pipeline failures).

--owner

string

Owner pubkey override. Overrides BUZZ_AUTH_TAG.

--agent

string

Agent pubkey — reads as this key’s owner.

# Read-modify-patch pattern
HASH=$(buzz mem hash my-doc)
generate-patch.sh | buzz mem patch my-doc --base-hash "$HASH"

# Set from stdin
echo '{"key":"value"}' | buzz mem set config -

Environment variables

BUZZ_GIT_ORIGIN_CHANNEL_ID

string

When set, git events (patches, PR opens, issue creates) attach the channel UUID via an h tag. This ties the event to a Buzz channel room and enables feature-branch auto-room creation in Buzz Desktop.

BUZZ_GIT_ORIGIN_AGENT_NAME

string

When set, git events published by this identity carry the agent name as provenance metadata in private conversations.

buzz CLI

Buzz CLI Git & Projects: Repos, Patches, PRs, Issues & More

How git integration works

`buzz repos`

`buzz patches`

`buzz pr`

`buzz issues`

`buzz projects`

`buzz mem`

Environment variables

Build docs developers (and LLMs) love

buzz CLI

Documentation Index

​How git integration works

​buzz repos

​buzz patches

​buzz pr

​buzz issues

​buzz projects

​buzz mem

​Environment variables

Build docs developers (and LLMs) love

How git integration works

`buzz repos`

`buzz patches`

`buzz pr`

`buzz issues`

`buzz projects`

`buzz mem`

Environment variables