nak (the nostr army knife)

Start a local bunker instance using nak bunker. You can specify relays with the --sec flag and authorized keys with -k.

Key features:

• --qrcode: Displays a QR code for the bunker URI.
• --persist: Saves metadata (secret key, relays, authorized client pubkeys) to disk.
• --profile <name>: Uses a named profile for persisted bunkers.
• nak bunker connect <uri>: Connects a nostrconnect:// client URI to a running bunker.

# Start a local bunker
~> nak bunker --sec <encrypted_key> relay.damus.io nos.lol relay.nsecbunker.com

# Start with a QR code
~> nak bunker --qrcode --sec <encrypted_key> relay.damus.io

# Start a persistent bunker
~> nak bunker --persist --sec <encrypted_key> relay.nsec.app nos.lol

# Connect a client to a running bunker
~> nak bunker connect 'nostrconnect://...'

The publish command can take raw text and automatically transform it into a structured Nostr event. It handles:

• Converting hashtags into tags.
• Converting npub codes into nostr:npub URIs.
• Converting domain names into https:// URIs.
• Adding p tags for mentioned users and q tags for mentioned events.
• Publishing to your configured "write" relays and the "read" relays of mentioned authors.

Flags:

• --reply <nevent|naddr|hex>: Sets the event to be a reply to the specified ID (automatically handles kind 1 or 1111).
• --confirm: Prompts for confirmation before publishing.

echo "#surely you're joking, mr npub1l2vyh47mk2p0qlsku7hg0vn29faehy9hy34ygaclpn66ukqp3afqutajft olas.app is broken again" | nak publish

The blossom command provides an interface for interacting with Blossom servers (Nostr file storage).

• Upload: Use nak blossom --server <server-url> --sec <secret-key> upload <file> to upload a file. It returns a JSON object containing the sha256 hash and the url.
• Download: Use nak blossom --server <server-url> download <sha256-hash> -o <output-file> to download a file.

~> nak blossom --server blossom.azzamo.net --sec 01 upload image.png
~> nak blossom --server aegis.utxo.one download acc8ea43d4e6b706f68b249144364f446854b7f63ba1927371831c05dcf0256c -o downloaded.png

Use the sync command to synchronize events between two different relays. This is useful for ensuring data consistency across the network.

~> nak sync relay1.com relay2.com

You can fetch an event from one relay and immediately republish it to a list of other relays using a pipe.

# Fetch an event from one relay and republish it to several others
nak req -i <event_id> nostr.wine/ nostr-pub.wellorder.net | nak event nostr.wine offchain.pub public.relaying.io eden.nostr.land atlas.nostr.land relayable.org

You can mount your Nostr identity as a FUSE filesystem using the fs command. This allows you to interact with your Nostr profile and notes as if they were local files.

To mount, use nak fs --sec <secret-key> <mount-point>. Once mounted, you can create new notes by writing to a file in the notes directory. The publication is staged: you must touch publish to commit the note to relays or rm new to cancel it.

~> nak fs --sec 01 ~/nostr
~> cd ~/nostr/npub1xxxxxx/notes/
~> echo "satellites are bad!" > new
~> touch publish

You can install nak using several methods depending on your environment:

• Shell script (One-liner): Best for quick installation on Unix-like systems.
• Go: Use go install if you have a Go environment configured.
• Homebrew (macOS): Use brew install nak.
• Arch Linux: Use paru -S nak-bin or yay -S nak-bin.
• Nix: Use nix-env --install nak.
• Manual: Download binaries from the GitHub releases page.
• Docker: Build and run directly from the source code.

# One-liner installation
curl -sSL https://raw.githubusercontent.com/fiatjaf/nak/master/install.sh | sh

# Go installation
go install github.com/fiatjaf/nak@latest

# Docker usage
docker build -t nak . && docker run nak event

Use the nak event command to generate a new Nostr event. By default, it uses the key 01. You can customize the content, tags, and signing key, and publish the event to specific relays.

# Create an event with the default key
nak event

# Create an event with custom content, tags, a specific key, and publish to multiple relays
nak event --sec 02 -c 'good morning' --tag t=gm nostr-pub.wellorder.net relay.damus.io

Use the --musig 2 flag to initiate a collaborative signing process. This is a two-step process where the first signer generates a secret code that must be provided to the second signer.

# Step 1: First signer generates the initial part of the signature
nak event --sec <secret_key> -k 'text note' -c 'hello' --musig 2

# Step 2: Second signer uses the secret code and the first signer's public key to complete the signature
nak event --sec <second_secret_key> --musig 2 -k 1 -ts <timestamp> -c 'hello' --musig-pubkey <first_signer_pubkey> --musig-nonce <nonce_from_step_1>

Use nak decode to turn NIP-19 codes (like note1...) into JSON objects, and nak encode to turn JSON objects back into NIP-19 codes (like nevent1...).

# Decode a note1 code and encode it back to nevent1 with a relay hint
nak decode note1ttnnrw78wy0hs5fa59yj03yvcu2r4y0xetg9vh7uf4em39n604vsyp37f2 | jq -r .id | nak encode nevent -r nostr.zbd.gg

# Decode a nevent1 code to see its contents
nak decode nevent1qqs94ee3h0rhz8mc2y76zjf8cjxvw9p6j8nv45zktlwy6uacjea86kgpzfmhxue69uhkummnw3ezu7nzvshxwec8zw8h7

Use nak req to query relays for events based on specific criteria like kind, tags, or limits. You can pipe the output to tools like jq to extract specific fields.

# Query relays for kind 1 events with tag t=gm, limiting to 2 results per relay
nak req -k 1 -t t=gm -l 2 nostr.mom nostr.wine nostr-pub.wellorder.net | jq .content

# Fetch events that are missing from a local JSONL file (negentropy sync)
nak req --only-missing ./events.jsonl -k 30617 pyramid.fiatjaf.com