nostr-client

A CLI-first Nostr client built with Node.js and TypeScript. Publish notes, read your feed, send zaps, and manage your identity — all from the terminal.

Why?

This project exists to provide a lightweight, scriptable way to interact with the Nostr network. Built to support the Bitcoin/Nostr community and the pg_sats project, it focuses on doing a few things well: posting, reading, identity, and zapping.

Prerequisites

• Node.js 18 or later
• TypeScript (installed as a dev dependency)
• A Nostr private key in nsec format

Installation

git clone https://github.com/jasonmassie01/nostr-client.git
cd nostr-client
npm install
npm run build

Create a .env file with your private key:

NOSTR_NSEC=nsec1your_key_here

Security: Your .env file is gitignored. Never share or commit your nsec.

Usage

Run commands with node dist/index.js <command> or npm start -- <command>.

For development, use npx ts-node src/index.ts <command> to skip the build step.

Commands

whoami — Show your profile

Displays your public key (npub and hex), profile metadata, and follower count.

node dist/index.js whoami

Output includes name, display name, bio, picture URL, NIP-05, Lightning address, website, and following count when available.

post <message> — Publish a note

Publishes a kind:1 text note to all configured relays in parallel.

node dist/index.js post "Hello from the terminal!"
node dist/index.js post "Building in public with #nostr"

Reports success/failure for each relay individually.

feed — View your feed

Fetches the latest 30 notes from people you follow (kind:3 contact list) plus your own notes. Displays author names, timestamps, and note IDs with color formatting.

node dist/index.js feed

zap <npub> <sats> [comment] — Send a Lightning zap

Creates a NIP-57 zap request and returns a Bolt11 Lightning invoice. Pay the invoice with any Lightning wallet to complete the zap.

node dist/index.js zap npub1abc...xyz 1000
node dist/index.js zap npub1abc...xyz 5000 "Great post!"

The recipient must have a Lightning address (lud16) or LNURL (lud06) in their profile.

help — Show help

node dist/index.js help

Command Reference

Command	Description
post <message>	Publish a kind:1 text note to relays
feed	Display latest notes from your contacts and yourself
whoami	Show your npub, profile info, and following count
zap <npub> <sats> [comment]	Create a NIP-57 zap request and get a Lightning invoice
help	Show help message

Configuration

Relays

The client connects to three default relays:

• wss://relay.damus.io
• wss://relay.nostr.band
• wss://nos.lol

To change relays, edit src/config.ts and rebuild.

Key Setup

Your Nostr identity is loaded from the NOSTR_NSEC environment variable. The client:

1. Reads the nsec from .env
2. Decodes it to a raw secret key
3. Derives your public key (npub) automatically

Architecture

src/
├── index.ts          CLI entry point — parses argv and routes to commands
├── config.ts         Key loading (nsec → secretKey/pubkey/npub) and relay list
├── pool.ts           Singleton SimplePool for relay WebSocket connections
├── format.ts         Terminal output helpers (colors, timestamps, note formatting)
└── commands/
    ├── post.ts       Publish kind:1 notes to relays in parallel
    ├── feed.ts       Fetch contact list, query notes, resolve profiles, display
    ├── whoami.ts     Fetch and display profile metadata and follow count
    └── zap.ts        NIP-57 zap request creation and LNURL invoice fetching

Key dependencies:

• nostr-tools — Event signing, encoding, NIP-57, relay pool
• ws — WebSocket client for Node.js relay connections
• dotenv — Environment variable loading

Roadmap

• Profile editing (update kind:0 metadata)
• DM support (NIP-04 / NIP-44 encrypted messages)
• Relay management (add/remove/list relays at runtime)
• Zap receipt verification (confirm zap was received)

Contributing

See CONTRIBUTING.md for development setup, project structure, and how to add new commands.

Author

Jason Massie

• GitHub: @jasonmassie01
• Nostr: jasonm@snort.social

License

MIT