Command reference
Every nostrfy command: init, start, stop, stats, upgrade and migrate-strfry, plus the CLI access lists and inbox/outbox subscription filters.
Overview
All commands accept --config <path> (default nostrfy.toml).
| Command | Description |
|---|---|
nostrfy init | Write a default nostrfy.toml and exit; the file is created 0600 |
nostrfy genkey | Generate a secret key for NIP-29 groups, write it into relay.private_key, set the config to 0600 and print the public key; aborts instead of writing if the file changed since it was read |
nostrfy check | Validate the config without side effects (also works while the relay is live; a port-in-use warning is expected) |
nostrfy start | Start as a daemon; --foreground runs in the terminal |
nostrfy stop | Stop the running daemon |
nostrfy restart | Stop and start again (re-reads the config) |
nostrfy stats | Show live statistics |
nostrfy upgrade [version] | Update the binary to the latest GitHub release (or the given version); downloads the matching platform asset, verifies its sha256 checksum and runs a --version probe, then atomically replaces the binary; concurrent runs are serialized with a lock file; never downgrades unless a version is given; --force reinstalls |
nostrfy migrate-strfry | Import events from a strfry relay — either run strfry export via --strfry-db, read a JSONL file with --input, or pipe it via stdin; re-runnable, with --dry-run, --since and optional settings merge |
Managing the access lists
The relay pubkey allow/deny lists and the Blossom upload allowlist live in LMDB and apply immediately — the running daemon is reloaded automatically:
nostrfy relay allow npub1...
nostrfy relay deny npub1...
nostrfy relay list
nostrfy blossom allow npub1...
nostrfy blossom deny npub1...
nostrfy blossom listA denied pubkey is always rejected when publishing and never served when reading.
nostrfy access unblockip <ip> removes an IP from the persisted NIP-86 blocked-IP list
(self-lockout recovery); restart the daemon to apply.
Inbox/outbox subscription filters
nostrfy extends the REQ filter syntax with two convenience keys for the inbox/outbox routing model — a nostrfy
extension, not part of any NIP. "outbox" expands to "authors": only events authored by the pubkey. "inbox" expands to "#p": only events addressed to the pubkey (mentions, replies, zaps and DMs). Values may be 64-hex or npub1 codes, or arrays that merge with an existing authors/#p key; an invalid pubkey rejects
the subscription:
["REQ", "my-feed", {"outbox": "npub1..."}]
["REQ", "mentions", {"inbox": "npub1...", "kinds": [1, 7]}]The endpoints are also write-restricted: /outbox accepts only events authored by the connection's
NIP-42-authenticated pubkey (server.outbox_write_policy = "any") or only the relay's own events
("relay"); /inbox accepts only events carrying a p tag.
Migrating from strfry
Bring an existing strfry relay's events over with one command. The migration is offline (stop the nostrfy relay first — it refuses to run while the database is held), reads strfry's own export format, and is safe to re-run: duplicates are skipped and deletion side effects are re-applied.
# dry run first — verifies every event, writes nothing
nostrfy migrate-strfry --strfry-db /var/lib/strfry-db --dry-run
# import (stop the nostrfy relay first)
nostrfy migrate-strfry --strfry-db /var/lib/strfry-dbIt also offers to merge the equivalent strfry settings into nostrfy.toml, and can resume with --since after an interrupted run. NIP-29 groups and NIP-43 roles are rebuilt from the imported
events on the first start. See the migration guide for the full runbook.