Skip to content

AGENTS.md

ncli is a Go CLI for the Nostr protocol: run a relay, stream/sync/query events, manage keys, and mine proof-of-work — all driven by YAML spec/config files. Assume the ncli binary is already on PATH. Global config comes from --config <file>, NCLI_*-prefixed env vars, ncli.yaml/relay.yaml in the current directory, a saved ncli relay context (see below), or $HOME, in that priority order.

Command Purpose
ncli apply -f <spec.yaml> Run a stream/sync/inspect workflow from a YAML spec
ncli dump -o <out.json> Export events to JSON from a relay, .db file, or prefs relays
ncli find <id> / -t <targets.yaml> Look up events by ID (hex/note/nevent) or author (npub/nprofile/nip-05), and/or filter, across targets; -f/--follow keeps the subscription open and prints each new event once as a JSON line (--state <file> resumes after a restart without gaps or repeats)
ncli dm send/read/prove/verify NIP-17 private messages through --signer: send --to <who> seals and gift-wraps (plus a copy to yourself); read --from <who>... opens only those senders’ seals (-f, --state, -S); prove gives a third party one message (seal + that payload’s message keys) and verify checks it with no key. -s/--relays is required
ncli form create/list/show/respond/withdraw/result NIP-PF forms through --signer: questions with the recommended option and why, answered in one response (the latest counts) and closed by the author with a result (decided, default, cancelled). Private (--to: gift-wrapped to each responder and to you), in a NIP-29 group (--group --relay) or public; a response the form refuses is refused before anything is sent
ncli profile set / relays set / follow / unfollow / mute / unmute Publish your profile (kind 0), relay lists (10002, DM 10050), follows (3) or mutes (10000) through --signer: each reads your current version and changes only what you name (relays set replaces the list it names, reporting what it drops); nothing is published unless every relay answers, or (without --create) if none has one, and never a list without people unless --allow-empty
ncli profile <identifier> Readable profile card for one identity — metadata, following count, relay list, Blossom servers, lightning address, and NIP-85 stats (rank, followers, zaps) from any relay that serves them — aggregated across every relay (not stopping at the first hit like find)
ncli event verify/get/show <ref...> Verify any event’s id and signature (plus author, kind, PoW, expiration, delegation, zap, --deleted, --cross-relays), print it raw, or show it as a card – from an nevent/note/naddr/hex id/kind:pubkey:d, event JSON, -f files or stdin, looked up on the reference’s relay hints, -s (or prefs) and the author’s NIP-65 outbox; no identity needed. verify exits 1 if any event is invalid
ncli event new/id/encode/seen/rebroadcast/thread/diff/unwrap/validate Build an unsigned event from flags or compute ids; spell an event as nevent/naddr with hints; list which relays hold it; copy it unchanged to --to relays; walk its NIP-10/NIP-22 thread; diff two events; decrypt a NIP-59 gift wrap with --identity or --signer (--from opens only those senders’ seals); run nmilat’s per-kind rules on it
ncli event react/reply/post/repost/delete/wrap Through --signer: a NIP-25 reaction (e/p/k, a, and the group’s h), a reply threaded for its target’s kind (NIP-10, a group’s kind 9, else NIP-22), a note, a NIP-18 repost, a NIP-09 deletion of your own events, or a NIP-59 gift wrap of any event
ncli ping <relay...> / -t <targets.yaml> Probe whether targets are reachable (connect + subscribe), no events fetched
ncli prefs relays add/list/remove/clear Manage the default relay list find/dump/ping/miner check fall back to
ncli relay --config <relay.yaml> Run the relay server (--check validates the config, failing on any unknown key, and exits; a start only warns about one); listen: host:port binds one address instead of every interface on port; gift wraps (1059) are served only to the pubkey their p names (recipientOnlyKinds, [] turns it off); groups.membershipNotices signs a seat notice (44100/44101) to a member gaining or losing a seat; httpBridge.count serves POST /count (NIP-45); presence answers who is online on POST /query (kind 40902 → relay-signed 20001); blossom serves Blossom uploads/downloads on the relay’s origin from a directory or S3 (MinIO); groups block hosts NIP-29 groups: roles (which roles may send which moderation kinds), roleDescriptions (kind 39003), admins (moderate every group), moderationLog, pendingJoins; agent_auth block enables NIP-AA (an agent key gains virtual membership from its owner’s NIP-43 membership via a NIP-OA credential, no separate enrollment); membership.roles says what each NIP-43 role may do (NIP-86 methods, group:<kind>, blossom.*, huddle.join, group.create) and groups.create who may create a group; nip86 block serves the NIP-86 management API on the relay URL so an app can moderate (ban pubkeys/events, allow/disallow kinds, block IPs, rename the relay; saved in <store>.moderation.json) and administer membership without a terminal; query block serves the NIP-CW POST /query bridge, a one-shot HTTP alternative to a WS REQ/EOSE round trip – NIP-98 there binds identity; results are further gated to the signer’s own NIP-43 membership when nip11.limitation.membership_required is set, same as REQ/COUNT; cache.profiles.stats serves NIP-85 user assertions (kind 30382 by #d: rank, followers/following, zaps received/sent, per coin) signed with nip11.privkey; cache.profiles.checks sets when NIP-05/lightning addresses are re-checked (TTL, retry backoff, per-host spacing; never on an index rebuild) and cache.profiles.scoring the profile score weights; cache.zaps serves the signed zap-ranking cache action (listed windows and coins, capped limit, cached); cache.relay.stats publishes the relay’s own NIP-66 kind 30166 (counts, zap totals, requirements); limits sets opt-in rate limits (unset = no limit; a public relay without any is warned)
ncli relay status / relay index list/rebuild/drop / relay jobs list/show/cancel / relay verify Monitor a running relay and its search, zap and stats indexes. The relay keeps each current on its own (catch-up after its feature was off, rebuild, rescore, freeing old data) as jobs with a trigger, progress and a summary; index list says each index’s state and what happens next. rebuild forces one (plan, progress, outcome; --json returns the job at once, --wait/--follow watch it, --detach, --dry-run); drop removes what an index whose feature is off still holds. relay verify <pubkey> --refresh re-checks a profile’s NIP-05/lightning address. Over the admin listener (admin.listen, default 127.0.0.1:<port+1>), signed with nip11.privkey
ncli relay dashboard / ncli relay metrics token add/list/remove Open the embedded dashboard locally, signed by the CLI; manage the tokens Prometheus scrapes /metrics with (admin.metrics). The relay-served dashboard signs in the relay’s key, nip86.admins or admin.pubkeys via a NIP-07 extension, an nsec (signed in the page; optionally saved as a password-encrypted NIP-49 ncryptsec in that browser) or NIP-46 (bunker://, nostrconnect://). A browser opening the relay URL gets a homepage built from NIP-11 (homepage: false disables it)
ncli relay members list/show/add/remove / ncli relay invites create/list/revoke / ncli relay roles list/create Administer a running relay’s NIP-43 membership over NIP-98 HTTP: enroll/remove members, issue/revoke invite codes, define roles
ncli relay context list/add/use/remove Save named relay --config shortcuts and switch the current one, so relay subcommands stop needing --config repeated on every call
ncli relay -c/--context <name> Run directly against a saved context by name (bypassing “current”); if <name> doesn’t exist yet, offers (or -q/--json auto-confirms) to create a minimal relay backed by a fresh vault identity under <AppConfigDir>/relays/<name>/
ncli bunker Run as a NIP-46 remote signer: approve/reject other clients’ signing requests from a live TUI, remembering per-app decisions so you aren’t re-prompted every time. Without a terminal (or with --json) it starts the signer in the background instead and prints its status — a second call reports the running one, conflict if --identity names a different key
ncli bunker attach/status/stop/connect/history / ncli bunker sessions list/grants/rename/revoke/revoke-grant/set-grant Reattach to, query, stop, or pair a running bunker daemon without opening the TUI; review resolved requests; manage each app’s remembered permissions
ncli bunker pending list/approve/reject / ncli bunker sessions set-grant Everything the TUI decides, from a script: list requests awaiting a decision, approve or reject one by id (--always remembers it, with --any-kind, --for <dur> or --uses <n> like the TUI’s buttons), or apply a --grants spec to an already-paired app
ncli signer serve / status / check Local policy signer on a unix socket: holds one key in memory and answers the NIP-46 method set as newline-delimited JSON (no relay, no encryption; socket permissions plus optional --allow-uid/--allow-gid authenticate). A kind: signer-policy file decides (default deny; selectors, deny_matching, rate limits, require: attestations such as a signed “approve ”; unwrap_from releases a decrypted gift wrap only when it holds a seal from a listed sender; nip44_message_keys must be named to be allowed). Built in: never signs its own key, never counts a self-signed or pre-start attestation, single-use attestations persisted in --state-dir. status probes it (exit 6 when down); check dry-runs a policy offline (exit 7 on any denial)
ncli id sign --signer / ncli publish --signer Sign through a socket signer: bunker+unix:///abs/path.sock (or unix://); --signer also takes an identity. id sign --attestations <file> passes events a policy requires. A policy denial is auth (exit 7). publish also logs in (NIP-42) with it, or with --auth-signer; find/dump --auth-identity and apply --auth-signer take the same forms plus bunker://, signing only the login
ncli nip98 <url> <method> Print a NIP-98 Authorization header for one HTTP request, signed with --identity or through --signer (whose policy decides which URLs); --payload-file binds the body, --value prints the value alone
ncli blossom upload/download/list/rm/mirror/report Client for the Blossom protocol (BUD-01..12): content-addressed blob storage authenticated with a Nostr identity
ncli blossom servers add/remove/list/discover Manage the default Blossom server list, optionally publishing/discovering it as a signed kind:10063 (BUD-03) event
ncli huddle list List the ephemeral transport rooms that currently have someone in them, with peer count and the protocol version each is pinned to — a room id is otherwise out-of-band knowledge, and space join on an unused one opens it rather than failing
ncli space create <id> Publish a new NIP-53 meeting space (kind:30312). --service defaults to --relay, which is what makes the space joinable with space join afterward — point it elsewhere to describe a space on a transport ncli itself can’t dial. id doubles as the huddle room id, so it’s rejected up front if it contains /, ?, # or % (put a human-readable name in --summary instead)
ncli space list / ncli space show <id> List every open space a relay knows about, or show one’s full detail — a space with no live session is still shown, since the space is the durable thing, a live call is just a property of it
ncli space join [id|naddr|room] Join a space’s voice/audio call and watch the live roster and who is speaking; plays the call in a -tags huddleaudio build (never captures a microphone). Given a NIP-53 activity instead of a room id (naddr, or a 30312:/30313: coordinate) it resolves the space to find the relay and room, and opens the kind:1311 conversation beside the roster — reply with <r>, quote with <y>, or --no-chat to omit it. Omitting the argument entirely joins --relay’s one open space, if there’s exactly one (errors listing every candidate if there’s more than one). Chat needs an activity: a 1311 message must name one, and a bare room id is not an addressable event. Without a terminal (or with --json) there is no roster view: it streams one JSON object per line (joined, participant_joined/left, speaking_started/stopped, chat, ended) until --duration or an interrupt. (Implemented in cli/huddle, mounted only under space — voice is one option a space can enable, not a separate top-level thing to join)
ncli space chat send/list <space> Post to or read a space’s kind:1311 conversation without joining its call — send takes --reply <id>/--quote <id>, list prints {"activity","messages":[...]} oldest first
ncli groups create/edit/delete/invite/join/leave Self-service NIP-29 relay-hosted-group writes — each a plain signed event (no admin HTTP surface), with a previous tag attached automatically; edit reads the group’s current metadata first and merges in only the flags passed, since the underlying event replaces metadata wholesale (including its subgroup Children list, always carried forward even when the edit doesn’t touch it)
ncli groups create/edit --parent <id> NIP-29 Subgroups: links a group under a parent (create --parent is create+link in one call; edit --parent "" detaches to root). Relay-enforced: no self-reference/cycle, parent must exist, submitter must also admin the new parent, and both groups must share the same --private/--public setting (a signed kind:39000 can’t be redacted per viewer, so a mixed-visibility link would permanently leak one group’s id via the other’s public side)
ncli groups tree Reads every visible kind:39000 and assembles the parent/child hierarchy locally (per NIP-29’s own recommended assembly) — text tree or --json for a scripted caller
ncli groups members add/remove / ncli groups pins set / ncli groups delete-event More NIP-29 writes: add/remove a member (optionally with roles), replace a group’s pinned-events list (whole list, not append — passing nothing clears every pin), or delete one of the group’s own events
ncli groups send/read/feed Group chat: send <group> <text> posts a kind 9 (-r quotes the message answered, -m tags a person); read <group> prints its messages (--thread, -f, --state); feed prints what mentions you across your groups. Every groups command takes --signer as well as --identity
ncli groups list / ncli groups show <group-id> Read a relay’s groups (metadata) or one group’s full detail (metadata/admins/members); --identity authenticates (NIP-42) so a member can see their own private group; omitted, it falls back to groups.identity or the vault’s sole entry, else stays anonymous. show names one group, so the relay refuses it outright (exit 7, auth) without membership — and, as of the relay’s own existence-oracle fix, identically for a group that doesn’t exist at all, not just a private one; list names none, so it silently drops private groups you’re not a member of instead
ncli id [identifier] Generate or inspect a Nostr keypair (local vault)
ncli id import Save an existing private key (nsec/hex/ncryptsec) to the vault, read from stdin or --file, never an argument; first valid line wins; re-running is a no-op and a key is never saved twice (--force relabels it)
ncli id relabel <identifier> <new-label> Rename a saved vault identity (by label, npub, hex, nprofile or nip-05) without supplying its key
ncli id rm <identifier> Remove a saved vault identity (by label, npub, hex, nprofile or nip-05), deleting the vault’s copy of its key; confirms first, --yes required with --json or no terminal
ncli id delegate Mint a NIP-26 delegation token
ncli id attest <npub|hex> Sign a NIP-OA owner attestation (--until, --kind) with --identity or through --signer (a socket signer’s nipoa_attest, allowed only by an attest policy rule); prints the ["auth", attester, conditions, sig] tag, verified
ncli id sign -e <events.json> -o <signed.json> Sign one or more unsigned events with a vault/nsec identity; -e -/-o - read stdin and print the signed events, so ncli event new | ncli id sign -e - -o - | ncli publish -e - works as a pipe
ncli decode <entity> Decode any NIP-19 bech32 entity (npub/nsec/note/nprofile/nevent/naddr), a NIP-CASH cash-token-family string, or a NIP-CW circlehub1… connection
ncli miner -e <event.yaml> Mine or check NIP-13 proof-of-work on an event
ncli version Build info + on-disk paths
ncli skills list/show/install List, print or install the agent skills built into the binary (the skills/ guides below, matching the installed version); install copies them to the required --dir, refusing to overwrite a differing file without --force

Every relay input (-s/--relays, prefs relays add, targets.yaml, apply flow entries) accepts a bare host with no ws(s):// scheme — relay.primal.net tries wss:// first, falling back to ws:// only if that fails and no scheme was given explicitly.

Every command’s actual result goes to stdout only; progress narration and errors go to stderr — so piping stdout into jq or a script’s parser never picks up log noise. --json and -q/--quiet are global flags (declared once on the root command, available on every subcommand) rather than per-command. id, id list, id import, id relabel, id rm, id sign, version, skills list/show/install, id delegate, id attest, nip98, relay --check, relay status/index/jobs/verify/metrics token, relay members/invites/roles, ping, miner mine/check, publish, huddle list, space create/ list/show/chat send/chat list, bunker/status/stop/ connect/history/sessions/pending, signer status/check, event verify/show/encode/seen/ rebroadcast/thread/diff/unwrap/validate/react/reply/post/repost/delete, groups create/edit/delete/invite/join/leave/ members/pins/delete-event/list/show/send/read/feed, dm send/read/verify, form create/list/show/respond/withdraw/result, profile set/relays set/follow/unfollow/mute/unmute, and prefs relays add/ remove/list/clear/prefs path are human-readable text by default and switch their success output to structured JSON on stdout with --json. find has no separate success-mode toggle because it’s JSON-only always, and its stdout is guaranteed to be exactly one JSON array on every successful run — [] when nothing matched, never bare null and never empty output — so a script never needs a no-result special case. The same holds for every list in any command’s --json output: an empty list is [], never null. space join and signer serve are the streaming commands, as are relay status --watch and relay index rebuild --follow / relay jobs show --follow under --json (one JSON object per line). Without a terminal or with --json, space join’s stdout is NDJSON (one JSON object per line, ending with an ended line), not a single document. signer serve always writes one decision object per line, for as long as it runs. find -f, dm read -f, groups read -f and groups feed -f stream too: one JSON object per line (an event, or for dm/groups the same message object dm read --json lists), until interrupted (exit 0). dm prove always prints its proof as JSON. -q/--quiet drops the stderr narration on any command (warnings/errors still show), for callers that can’t rely on stdout/stderr being captured separately.

find/dump/miner check query one or more targets and tolerate individual failures — an unreachable relay is logged and skipped rather than failing the whole query, so a mix of reachable and unreachable targets still returns a normal (possibly partial) result with exit 0. But if every target fails to connect or times out, that’s a network error (see the table below), not a false-successful empty result — []/exit 0 means “queried successfully, found nothing,” never “couldn’t check.” ping is the opposite: reachability is exactly what it’s testing for, so any unreachable target is a failure (internal, exit 1), not tolerated and logged like it is elsewhere. Its per-relay results still go to stdout when it fails, so a script can see which targets were down.

Failures: exactly one top-level error report, always on stderr, never stdout. In text mode it takes one of three shapes, and --json replaces all three with a single {"error", "code", "retryable", "input"} line (plus reason/detail on a failed NIP-42 login, see below):

shape when looks like
help alone, no error line the command was invoked bare — no arguments and none of its own flags (ncli decode, ncli miner) the command’s --help text, on stderr
Error: <msg>, blank line, then help something was supplied and it was wrong — bad arg count, unknown flag or subcommand, conflicting flags Error: in red on a TTY, then the help
Error: <msg> alone the invocation was fine and the operation failed (ncli ping with no relays, a bad identifier) one line; help wouldn’t help

The first shape still exits non-zero with its usual code — help is shown instead of scolding, not instead of failing, so a mistyped subcommand is never mistaken for success. Error: is red only on a real terminal, and never when NO_COLOR is set or stderr is piped.

code exit retryable meaning
usage 2 no bad/missing/conflicting flags/args/config, a relay-side feature that isn’t turned on (e.g. relay members ... against a relay with membership.enabled: false), or a group command (relay members/invites/roles/index/jobs/metrics, prefs, prefs relays, miner, blossom, blossom servers, bunker sessions) invoked without one of its own subcommands
invalid_input 3 no a supplied value failed validation/parsing (bad identifier, URL, key, duration, kind, …)
not_found 4 no the referenced thing doesn’t exist (vault entry, configured relay, …)
conflict 5 yes collides with existing state (vault label taken, another job running on that index)
network 6 yes a remote call failed (relay connection, admin HTTP request, nip-05 fetch)
auth 7 no wrong credentials or a rejected signature
unsupported 8 no the target server doesn’t support the requested capability at all (blossom list, upload --optimize or mirror against a server without that endpoint, or any Blossom endpoint answering 3xx, 405 or 501; huddle list/space join against a relay with huddles disabled), distinct from not_found’s “this one specific resource is missing”
internal 1 no anything else (fallback bucket)

A failed NIP-42 login (publish, find, dump, apply against a relay that requires one) is auth with input = the relay URL and reason = login_required (no signer given), signer_refused (detail = the signer’s reason, with its rule) or relay_refused (detail = the relay’s message). Each connection signs at most one kind 22242, for the URL it dialed, through --signer/--auth-signer/--auth-identity (bunker+unix://, bunker://, or a key).

input, when present, is the single specific value that caused the failure (an identifier, file path, relay URL, --kinds token, …) — omitted when there’s no one clean value, or when the value is private-key material (never echoed, even malformed). retryable lets an agent decide whether to back off and retry (network/conflict) or fix the input and try again (everything else) without string-matching the message. No command double-reports the same failure in two shapes, and --json never prints help at all — just the one structured line, whichever of the three text shapes the failure would otherwise have taken.

Waiting: any command that blocks on the network (find, dump, ping, publish, profile, miner check, every blossom and relay admin subcommand) animates a spinner on stderr while it waits, with the per-relay progress narration still printed above it. The spinner is off under --json, under -q/--quiet, when NO_COLOR is set, and whenever stderr isn’t a terminal — so captured output is byte-identical to before.

--json also switches every other stderr log line (progress narration, warnings, a partial/recoverable failure like one unreachable target in a multi-target query) from a colored console line to a single-line JSON object ({"level","message","time",...}, zerolog’s native shape) — not just the command’s own final error — so a script parsing stderr never has to handle two different log formats depending on where in the run the message came from.

Before attempting a task, read the matching skill

Section titled “Before attempting a task, read the matching skill”

This repo ships deep, example-driven guidance in skills/, one file per area, each with runnable commands and hard-won gotchas verified against the Go source (not just the README). Read the relevant one before writing YAML or invoking a command in that area:

  • Writing or running an apply spec (stream/sync/inspect) → skills/ncli-apply/SKILL.md
  • Querying/exporting events, or testing relay connectivity (dump, find, ping, filters.yaml, targets.yaml, prefs) → skills/ncli-query/SKILL.md
  • Configuring or operating a relay (relay.yaml, relay status/index/ jobs/verify, profile checks, scores and NIP-85 stats, Prometheus metrics and the dashboard (admin:, relay metrics token, relay dashboard), NIP-43 membership via relay members/invites/roles, or NIP-AA agent_auth) → skills/ncli-relay-ops/SKILL.md
  • Generating/importing/managing keys or delegation tokens (id, id import, id delegate), or decoding a NIP-19 entity, cash token, or circlehub1… connection (decode) → skills/ncli-identity/SKILL.md
  • Checking whether an event is authentic, fetching or showing one by nevent/note/naddr, seeing which relays hold it, rebroadcasting it, walking its thread, unwrapping a gift wrap, or building/signing/ publishing an event in a pipe (event ...) → skills/ncli-event/SKILL.md
  • Mining or verifying proof-of-work (miner) → skills/ncli-miner/SKILL.md
  • Running ncli as a remote NIP-46 signer (bunker, bunker attach/ status/stop/sessions/history/connect), including pairing an agent as its NIP-46 client so it can get events signed without holding a raw key → skills/ncli-bunker/SKILL.md
  • Running a local policy signer for an agent (signer serve/status/ check, a signer-policy file, a Kubernetes sidecar) or signing through one (id sign --signer, publish --signer) → skills/ncli-signer/SKILL.md
  • Uploading/fetching/managing content on Blossom media servers (blossom upload/download/list/rm/mirror/report/servers) → skills/ncli-blossom/SKILL.md
  • Listing a relay’s live ephemeral transport rooms (huddle list) or the audio/video/chat details of an in-progress call → skills/ncli-huddle/ SKILL.md
  • Creating, listing, or showing a NIP-53 meeting space, or joining one’s voice call (space create/list/show/join) → skills/ncli-space/SKILL.md
  • Creating or administering a NIP-29 relay-hosted group (groups create/ edit/delete/invite/join/leave/members/pins/delete-event/ list/show) → skills/ncli-groups/SKILL.md
  • Talking on Nostr through a signer: private messages and proving one (dm send/read/prove/verify), group chat (groups send/read/feed), reactions, replies and posts (event react/reply/post/repost/delete), your own profile and lists (profile set/relays set/follow/mute), or waiting for new events (find -f) → skills/ncli-messaging/SKILL.md
  • Asking or answering NIP-PF forms: questions with a recommended option, answered in one response, closed with a result (form create/list/show/ respond/withdraw/result) → skills/ncli-forms/SKILL.md

These skills assume only the ncli binary is available — no access to this source tree. Each is also built into the binary: ncli skills show <name> prints it, ncli skills install copies them into an agent’s skills dir. (Building/contributing to ncli itself is a different task — see CONTRIBUTING.md and .agents/skills/local-verify.)