Skip to content

CLI.md

Latest commit

 

History

History
160 lines (124 loc) · 4.96 KB

CLI.md

File metadata and controls

160 lines (124 loc) · 4.96 KB
Raw

Nostream CLI

Nostream ships a unified command-line interface:

nostream --help
pnpm run cli -- --help

When run with no arguments in an interactive terminal, nostream launches an interactive TUI. In non-interactive environments, it prints help and exits successfully.

Exit Codes

  • 0: success
  • 1: runtime/validation error
  • 2: usage error (invalid command/options)

Core Commands

nostream start [--tor] [--i2p] [--nginx] [--debug] [--port 8008]
nostream stop [--all|--tor|--i2p|--nginx|--local]
nostream info [--tor-hostname] [--i2p-hostname] [--json]
nostream update
nostream clean
nostream setup [--yes] [--start]
nostream seed [--count 100]
nostream invite create [--uses N] [--expires-in <seconds>] [--json]
nostream import [file.jsonl|file.json] [--file file.jsonl|file.json] [--batch-size 1000]
nostream export [output] [--output output] [--format jsonl|json]

NIP-43 invite codes

Join (kind 28934) is already implemented. Operators mint a claim string and share it out of band; the client then publishes a join request with a claim tag.

# Local PostgreSQL (DB_URI or DB_HOST in the environment / .env)
nostream invite create
nostream invite create --uses 3 --expires-in 86400 --json

# Docker: Postgres is not published to the host
docker compose exec nostream node src/cli/index.js invite create

--uses defaults to nip43.defaultMaxUses (1). --expires-in defaults to nip43.inviteCodeExpirySeconds (600 = 10 minutes). --expires-in must be a positive integer; never-expiring codes are a yaml policy (nip43.inviteCodeExpirySeconds: 0), not a CLI flag. The printed code is the first line of human output so scripts can capture it. If info.self is a hex pubkey or npub1…, it is stored as created_by.

This does not yet generate kind 28935 on REQ or publish membership list events.

Removed Legacy Wrappers

The old shell wrapper scripts are no longer shipped in scripts/. Use the unified nostream CLI directly instead:

scripts/start                -> nostream start
scripts/start_with_tor       -> nostream start --tor
scripts/start_with_i2p       -> nostream start --i2p
scripts/start_with_nginx     -> nostream start --nginx
scripts/stop                 -> nostream stop
scripts/print_tor_hostname   -> nostream info --tor-hostname
scripts/print_i2p_hostname   -> nostream info --i2p-hostname
scripts/update               -> nostream update
scripts/clean                -> nostream clean

Configuration Commands

nostream config list
nostream config list --json
nostream config get <path>
nostream config get <path> --json
nostream config set <path> <value> [--type inferred|json] [--validate|--no-validate] [--restart]
nostream config validate

nostream config env list [--show-secrets]
nostream config env get <key> [--show-secrets]
nostream config env set <key> <value>
nostream config env validate

Path syntax supports dot keys and array indexes:

nostream config get limits.event.content[0].maxLength
nostream config set limits.event.content[0].maxLength 2048
nostream config set nip05.domainWhitelist '["example.com","relay.io"]' --type json

Development Commands

nostream dev db:clean [--all|--older-than=30|--kinds=1,7,4] [--dry-run] [--force]
nostream dev db:reset [--yes]
nostream dev seed:relay
nostream dev docker:clean [--yes]
nostream dev test:unit
nostream dev test:cli
nostream dev test:integration

TUI Navigation

Run:

nostream

Main menu includes:

  • Start relay
  • Stop relay
  • Configure settings
  • Manage data (export/import)
  • Development tools
  • View relay info
  • Exit

TUI behavior highlights:

  • Each submenu includes an explicit Back option, so you can return without using signal keys.
  • Start menu prompts for Tor/I2P/Debug, optional custom port, and final confirmation.
  • Configure menu offers guided editing for common categories such as payments, network, and limits.
  • Advanced dot-path get/set remains available for full settings access.
  • Manage menu asks for import/export format and file paths.
  • Dev menu displays explicit destructive warnings before DB reset/clean and Docker clean.

Common Workflows

# Start relay with Tor + I2P
nostream start --tor --i2p

# Print Tor hostname
nostream info --tor-hostname

# Machine-readable output for automation
nostream info --json
nostream config list --json
nostream config get payments.enabled --json

# Import and export events
nostream import --file ./events.jsonl --batch-size 500
nostream import --file ./events.json --batch-size 500
nostream export --output backup.jsonl --format jsonl
nostream export --output backup.json --format json

# Update YAML settings and restart relay
nostream config set payments.enabled true --restart

# Update env settings
nostream config env set RELAY_PORT 8008
nostream config env get SECRET --show-secrets
nostream config env validate

# Mint a NIP-43 invite code (kind 28934 join)
nostream invite create --json
docker compose exec nostream node src/cli/index.js invite create