# nostr-cli

A command-line tool for the Nostr protocol. Post notes, send encrypted DMs (NIP-17/NIP-44), query events, create raw events, publish long-form articles (NIP-23), manage accounts, follow users, and interact with relays.

## Quick Install

```bash
curl -sL https://nostrcli.sh/install.sh | bash
brew install xdamman/tap/nostr
```

## Core Features

- **Pipe-friendly**: `echo "hello" | nostr` posts a note, `echo "msg" | nostr dm user` sends a DM
- **Structured output**: `--json` (enriched, pretty), `--jsonl` (one line per event), `--raw` (wire format)
- **Auto-detection**: Colors off when piped, stdin read as input, NO_COLOR respected
- **NIP-17 DMs**: Gift-wrapped encrypted DMs by default (NIP-44 encryption), NIP-04 legacy with `--nip04`
- **Long-form**: Publish NIP-23 articles from markdown with YAML frontmatter
- **Event queries**: Flexible filters with `--kinds`, `--since`, `--until`, `--author`, `--filter`, `--me`
- **Live streaming**: `--watch` on events, DMs, and user feeds
- **Non-interactive**: `nostr login --nsec <key>`, `nostr post "msg"`, `nostr dm user "msg" --jsonl`

## Commands

### Posting & Messaging
- `nostr post [message]` — Post a text note (kind 1). Flags: `--tag`, `--tags`, `--dry-run`, `--json`/`--jsonl`/`--raw`
- `nostr post -f <file>` — Publish long-form article (NIP-23, kind 30023). Flags: `--title`, `--summary`, `--image`, `--slug`, `--draft`, `--hashtag`
- `nostr post --long` — Write long-form in built-in editor
- `nostr reply <eventId> [message]` — Reply with NIP-10 threading. Flags: `--tag`, `--tags`, `--json`
- `nostr dm <user> [message]` — Send NIP-17 gift-wrapped DM. Flags: `--nip04`, `--watch`, `--since`, `--tag`, `--json`/`--jsonl`
- `nostr events --kinds <n>` — Query events with filters. Flags: `--since`, `--until`, `--author`, `--limit`, `--decrypt`, `--watch`, `--filter`, `--me`
- `nostr event new --kind <n> --content <text>` — Create raw event. Flags: `--tag`, `--tags`, `--pow`, `--dry-run`

### Account Management
- `nostr login` — Create or import account. Flags: `--new`, `--nsec`
- `nostr switch [account]` — Switch active account (interactive picker without args)
- `nostr accounts` — List all local accounts. Flags: `--json`
- `nostr profile [user]` — View profile. Flags: `--refresh`, `--json`
- `nostr profile update` — Edit profile interactively

### Social Graph
- `nostr follow <user>` — Follow user (kind 3)
- `nostr unfollow <user>` — Unfollow user
- `nostr following` — List followed users. Flags: `--refresh`, `--json`
- `nostr [user]` — View user profile + notes. Flags: `--watch`, `--limit`, `--json`

### Configuration
- `nostr alias <name> <user>` / `nostr aliases` / `nostr alias rm <name>` — Manage aliases
- `nostr relays` / `nostr relays add <url>` / `nostr relays rm <url>` — Manage relays
- `nostr sync` — Sync events with relays. Flags: `--json`, `--relay`

### Global Flags
- `--account <npub|alias>` — Use a specific account
- `--timeout <ms>` — Relay timeout (default: 2000)
- `--no-color` — Disable colors
- `--json` / `--jsonl` / `--raw` — Output formats

## User Format

A `<user>` can be: npub1... | local alias | user@domain.com (NIP-05)

## Resources

- Website: https://nostrcli.sh
- Source: https://github.com/xdamman/nostr-cli
- Skill (full reference): https://nostrcli.sh/skill/SKILL.md
- AGENTS.md: https://github.com/xdamman/nostr-cli/blob/main/AGENTS.md