hoot - A Nostr CLI Tool

A simple command-line tool for using the Nostr network. It keeps your keys safe, lets you manage your profile, and supports multiple relays. It's made for fun, not serious use.

Features

Safe storage of private keys
Post messages to multiple relays
View and edit profile information (editing is still being worked on)
List recent posts
Customizable relay list
Lightning tips via NWC
NIP-89 app handler registration and discovery

NIP Support

NIP	Name	Status
NIP-01	Basic protocol flow	✅ Supported
NIP-04	Encrypted Direct Messages	✅ Supported
NIP-19	bech32-encoded entities (nsec, npub, note, nprofile)	✅ Supported
NIP-42	Authentication of clients to relays	🔲 Not supported
NIP-46	Nostr Connect (remote signing)	✅ Supported (TUI)
NIP-47	Nostr Wallet Connect (Lightning)	✅ Supported
NIP-57	Lightning Zaps	🔲 Not supported
NIP-65	Relay List Metadata	🔲 Not supported
NIP-89	Recommended Application Handlers	✅ Supported

Quick Start

Get up and running in minutes:

1. Store Your Key

hoot -s -k nsec1...

Enter encryption password:
Storing key | Storing key / Storing key - Storing key done

2. Update Your Profile

hoot -u '{"name":"YourName","about":"Your bio here"}'

Loading key | Loading key / Loading key done
Loaded relays:
 - wss://purplerelay.com/
 - wss://nos.lol/
 - wss://relay.damus.io
 - wss://relay.nostr.band
Updating profile | Updating profile / ... done
Profile update published to 3/4 relays

3. View Your Profile

hoot -p

Loading key | Loading key done
Loaded relays: [4 relays]
Retrieving profile | Retrieving profile done
Your profile:
name=YourName,about=Your bio here

4. Post a Message

hoot -m "Hello Nostr! 🚀 #introduction"

Publishing post | Publishing post / ... done
Successfully published to relay
Successfully published to relay
Successfully published to relay

5. List Your Posts

hoot -l

Last 4 posts from your profile:
Created: Wed, 25 Mar 2026 14:25:19 EDT
Content: Hello Nostr! 🚀 #introduction

6. View DMs

hoot -dms

Loading DMs | Loading DMs / ... done
Your recent direct messages:

Installation

From Source

Clone the repository:

git clone https://github.com/oth-body/hoot.git
cd hoot

Build the binary:
```
make build
# or: go build -o hoot .
```

Install to PATH:

sudo make install
# or: sudo mv hoot /usr/local/bin/

Homebrew (macOS/Linux)

brew tap oth-body/hoot
brew install hoot

AUR (Arch Linux)

yay -S hoot-bin
# or: paru -S hoot-bin

Download Binary

Download the latest release for your platform from GitHub Releases:

# Linux amd64
curl -sL https://github.com/oth-body/hoot/releases/latest/download/hoot-linux-amd64.tar.gz | tar xz
sudo mv hoot /usr/local/bin/

# macOS arm64 (M1/M2)
curl -sL https://github.com/oth-body/hoot/releases/latest/download/hoot-darwin-arm64.tar.gz | tar xz
sudo mv hoot /usr/local/bin/

Self-Update

If you already have hoot installed:

hoot -check-update  # Check for updates
hoot -update        # Update to latest version

Prerequisites

Configuration

Relay Configuration

Create a relays.txt file in:

Your config directory:
- Linux: ~/.config/nostr-cli/
- macOS: ~/Library/Application Support/nostr-cli/
- Windows: %APPDATA%\nostr-cli\

Example relays.txt:

wss://relay.damus.io
wss://relay.nostr.band
wss://nostr.wine

If no relays.txt is found, the above default relays will be used.

Usage

Hoot can be used in two modes: Interactive TUI (Terminal User Interface) or CLI (Command Line Interface).

Interactive TUI Mode

Simply run hoot without any flags to launch the interactive terminal interface:

hoot

The TUI provides:

Login options: Enter nsec directly, use saved profile, or scan QR code (NIP-46)
Multi-profile support: Save and switch between multiple Nostr accounts
Post composer: Write and publish notes
Feed viewer: Browse recent posts from the network
Relay management: Add, remove, and configure relays
Tipping: Send sats to other users via Lightning

TUI Navigation

Use ↑/↓ arrow keys to navigate menus
Press Enter to select an option
Press Esc to go back
Press q to quit

CLI Mode

Use command-line flags for scripting or quick actions.

Store Your Private Key

hoot -s -k <your-private-key>

You'll be prompted to create an encryption password.

View Your Public Key

hoot

Post a Message

hoot -m "Hello Nostr! #introduction"

Hashtags are automatically extracted and added as tags.

List Recent Posts

hoot -l

View Profile

hoot -p

Update Profile

hoot -u '{"name":"Alice","about":"Nostr enthusiast","lud16":"alice@getalby.com"}'

Using Custom Relays for a Single Command

hoot -r "wss://relay1.com,wss://relay2.com" -m "Hello from custom relays!"

Tipping with NWC (Nostr Wallet Connect)

Hoot supports sending Lightning tips via NWC.

Set up your NWC wallet

hoot -nwc "nostr+walletconnect://..."

Get your NWC URI from a compatible wallet like Alby or Mutiny.

Send a tip

# Tip by npub
hoot -tip 100 -user npub1...

# Tip by hex pubkey
hoot -tip 100 -user <hex-pubkey>

# Tip directly to a Lightning address
hoot -tip 100 -user alice@getalby.com

NIP-89 App Handlers

Register your app as a handler for specific event kinds:

hoot -register-handler "1,6" -platform web -url-template "https://myapp.com/e/<bech32>"

Recommend an app for handling a kind:

hoot -recommend "pubkey:d-identifier:1"

Find handlers for a specific kind:

hoot -find-handlers 1

All CLI Flags

Flag	Description
`-m "message"`	Post a message to Nostr
`-k <key>`	Private key to store (use with `-s`)
`-s`	Store a new private key
`-r "relay1,relay2"`	Comma-separated list of relay URLs
`-l`	List your last 4 posts
`-p`	View your profile info
`-u '{"name":"..."}`	Update profile with JSON
`-dms`	View your direct messages
`-replies "event-id"`	View replies/reactions for a specific event
`-version`	Display version info
`-nwc "uri"`	Set NWC URI for tipping
`-tip <sats>`	Amount to tip (use with `-user`)
`-user <npub/hex/lud16>`	User to tip
`-register-handler "kinds"`	Register as handler for event kinds
`-platform <platform>`	Platform for handler (web, ios, android)
`-url-template "url"`	URL template for handler
`-recommend "pk:d:kind"`	Recommend an app for a kind
`-find-handlers <kind>`	Find handlers for a specific kind
`-check-update`	Check for available updates
`-update`	Update hoot to the latest version

Environment Variables

Variable	Description	Default	Example
`HOOT_PASSWORD`	Encryption password for key storage (automation)	-	`export HOOT_PASSWORD=mysecurepass`
`HOOT_BCRYPT_COST`	Bcrypt hash cost (4-31, higher = more secure but slower)	10	`export HOOT_BCRYPT_COST=12`
`HOOT_RELAY_CONNECT_TIMEOUT`	Timeout for relay connections	10s	`export HOOT_RELAY_CONNECT_TIMEOUT=30s`
`HOOT_QUERY_TIMEOUT`	Timeout for event queries	10s	`export HOOT_QUERY_TIMEOUT=30s`
`HOOT_DM_QUERY_TIMEOUT`	Timeout for DM queries	15s	`export HOOT_DM_QUERY_TIMEOUT=1m`
`HOOT_SIGN_EVENT_TIMEOUT`	Timeout for signing events (NIP-46)	30s	`export HOOT_SIGN_EVENT_TIMEOUT=2m`
`HOOT_PUBLISH_TIMEOUT`	Timeout for publishing events	5s	`export HOOT_PUBLISH_TIMEOUT=10s`

Common Workflows

Complete Setup

# 1. Store your key
hoot -s -k nsec1...

# 2. Configure custom relays
mkdir -p ~/.config/nostr-cli
cat > ~/.config/nostr-cli/relays.txt << EOF
wss://relay.damus.io
wss://relay.nostr.band
wss://nostr.wine
EOF

# 3. Post introduction
hoot -m "Hello Nostr! #introduction"

Post with Hashtags and Custom Relays

hoot -r "wss://my-relay.com,wss://backup-relay.com" \
     -m "Just deployed hoot v0.0.4! 🎉 #go #nostr #opensource"

View and Reply

# See your recent posts
hoot -l

# View replies to a specific note
hoot -replies note1abc123...

# View your DMs
hoot -dms

Profile Management

# View your profile
hoot -p

# Update with Lightning address
hoot -u '{"name":"Alice","about":"Building on Nostr","lud16":"alice@getalby.com"}'

# Full profile update
hoot -u '{
  "name": "Alice Nostr",
  "about": "Building on Nostr | Go developer",
  "picture": "https://example.com/profile.png",
  "banner": "https://example.com/banner.png",
  "lud16": "alice@getalby.com",
  "nip05": "alice@example.com"
}'

Lightning Tips

# Setup NWC (one-time)
hoot -nwc "nostr+walletconnect://..."

# Tip by npub (100 sats)
hoot -tip 100 -user npub1abc123...

# Tip by Lightning address
hoot -tip 500 -user alice@getalby.com

NIP-89 App Handlers

# Register your app as a handler for kinds 1 and 6
hoot -register-handler "1,6" \
     -platform web \
     -url-template "https://myapp.com/e/<bech32>"

# Recommend an app
hoot -recommend "pubkey123:my-app:1"

# Find handlers for kind 1 (text notes)
hoot -find-handlers 1

Troubleshooting

See TROUBLESHOOTING.md for common errors and solutions.

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 51 Commits
aur		aur
cache		cache
homebrew		homebrew
nip46		nip46
tui		tui
workflows		workflows
.gitignore		.gitignore
.goreleaser.yaml		.goreleaser.yaml
Makefile		Makefile
README.md		README.md
TROUBLESHOOTING.md		TROUBLESHOOTING.md
go.mod		go.mod
go.sum		go.sum
hoot-test		hoot-test
hoot.exe		hoot.exe
hoot.go		hoot.go
hoot_test.go		hoot_test.go
relays.txt		relays.txt
relays.txt.example		relays.txt.example
test_dms_replies.sh		test_dms_replies.sh

Folders and files

Latest commit

History

Repository files navigation

hoot - A Nostr CLI Tool

Features

NIP Support

Quick Start

1. Store Your Key

2. Update Your Profile

3. View Your Profile

4. Post a Message

5. List Your Posts

6. View DMs

Installation

From Source

Homebrew (macOS/Linux)

AUR (Arch Linux)

Download Binary

Self-Update

Prerequisites

Configuration

Relay Configuration

Usage

Interactive TUI Mode

TUI Navigation

CLI Mode

Store Your Private Key

View Your Public Key

Post a Message

List Recent Posts

View Profile

Update Profile

Using Custom Relays for a Single Command

Tipping with NWC (Nostr Wallet Connect)

Set up your NWC wallet

Send a tip

NIP-89 App Handlers

All CLI Flags

Environment Variables

Common Workflows

Complete Setup

Post with Hashtags and Custom Relays

View and Reply

Profile Management

Lightning Tips

NIP-89 App Handlers

Troubleshooting

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages