@tostr-app/cli

Command-line interface for Tostr — publish, search, and inspect torrent metadata on the Nostr network.

Installation

# From npm (once published)
npm install -g @tostr-app/cli

# From the monorepo
pnpm --filter @tostr-app/cli build
node packages/cli/dist/index.js --help

Authentication

Publishing requires a Nostr private key. Provide it via environment variable (recommended — keeps it out of shell history) or the --private-key flag.

# Preferred: set once in your shell profile
export TOSTR_PRIVATE_KEY=a1b2c3d4...   # 64-char hex nsec

# Or pass inline (less safe)
tostr publish ./file.iso --title "My Torrent" --private-key a1b2c3d4...

To generate a fresh keypair:

node -e "
  import('@tostr-app/core').then(({ generateKeypair }) => {
    const { privateKey, publicKey } = generateKeypair();
    console.log('Private key:', privateKey);
    console.log('Public key: ', publicKey);
  });
"

Commands

publish <path>

Creates torrent metadata from a local file or directory, signs a kind 2003 Nostr event, and publishes it to relays.

tostr publish <path> [options]

Options:
  --title <string>        Torrent display name (required)
  --description <string>  Long description
  --tags <csv>            Comma-separated hashtags
  --private-key <hex>     Private key (or TOSTR_PRIVATE_KEY env var)
  --relay <url>           Additional relay (repeatable)
  --verbose               Debug output

Examples:

# Single ISO file
tostr publish ./ubuntu-24.04-desktop-amd64.iso \
  --title "Ubuntu 24.04 LTS" \
  --description "Official Ubuntu 24.04 LTS desktop image, amd64" \
  --tags "linux,ubuntu,iso"

# Directory of files
tostr publish ./my-dataset/ \
  --title "Climate Dataset 2024" \
  --description "Monthly temperature records, CSV format" \
  --tags "science,climate,data"

# Add extra relays beyond the defaults
tostr publish ./archive.tar.gz \
  --title "Project Archive" \
  --relay wss://nostr.wine \
  --relay wss://relay.nostr.band

# Verbose mode to debug relay connections
tostr publish ./file.mkv \
  --title "Documentary" \
  --verbose

Output:

Creating torrent...
Publishing to relays...

Event ID: 3a9f2b1c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1
nevent:   nevent1qqsr4m9k...
Magnet:   magnet:?xt=urn:btih:a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0&dn=Ubuntu+24.04+LTS&tr=wss%3A%2F%2Frelay.damus.io

search <query>

Searches for torrent events (kind 2003) across Nostr relays using NIP-50 full-text search. Waits for EOSE then prints results.

tostr search <query> [options]

Options:
  --tags <csv>     Filter by hashtags (comma-separated)
  --limit <n>      Max results (default: 20)
  --json           Output as JSON instead of table
  --relay <url>    Additional relay (repeatable)
  --verbose        Debug output

Examples:

# Basic full-text search
tostr search "ubuntu"

# Narrow by hashtag
tostr search "linux" --tags "iso,amd64"

# Multiple tags
tostr search "python" --tags "software,library"

# Large result set
tostr search "debian" --limit 50

# Machine-readable output for scripting
tostr search "ubuntu" --json | jq '.[].metadata.infoHash'

# Search on a specific relay that indexes kind 2003
tostr search "linux" --relay wss://nostr.wine

Table output:

Title                             Hash        Files       Size   Age  Author
----------------------------------------------------------------------------------------------
Ubuntu 24.04 LTS                  a1b2c3d4        1      1.4 GB    2h  npub1abc...defg
Debian 12 Bookworm                f9e8d7c6        1      3.7 GB    5d  npub1xyz...uvwx
Arch Linux 2025.01                11223344        1    820.5 MB    1d  npub1qrs...mnop

JSON output (excerpt):

[
  {
    "metadata": {
      "infoHash": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0",
      "title": "Ubuntu 24.04 LTS",
      "description": "Official desktop ISO",
      "files": [{ "name": "ubuntu-24.04-desktop-amd64.iso", "size": 1500000000 }],
      "trackerRelays": ["wss://relay.damus.io", "wss://nos.lol"],
      "tags": ["linux", "ubuntu"],
      "externalIds": []
    },
    "magnetUri": "magnet:?xt=urn:btih:a1b2c3d4...",
    "eventId": "3a9f2b1c...",
    "pubkey": "d8f3a2e1...",
    "createdAt": 1737000000
  }
]

info <nevent-or-id>

Fetches a single kind 2003 event by its nevent bech32 string or 64-char hex event ID, and prints all metadata plus any kind 2004 comments.

tostr info <nevent-or-id> [options]

Options:
  --relay <url>    Additional relay (repeatable)
  --verbose        Debug output

Examples:

# By nevent (includes relay hints — most reliable)
tostr info nevent1qqsr4m9kfd3xjmn5wdhhqat9wdsf86n0depk2empv4udr9e3ld3zqcppemhxue69uhkummn9ekx7mp0qgsr4m9k...

# By raw 64-char hex event ID (searches default relays)
tostr info 3a9f2b1c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1

# Add a relay hint if the event isn't on default relays
tostr info 3a9f2b1c... --relay wss://nostr.wine

# Combine multiple relay hints
tostr info 3a9f2b1c... \
  --relay wss://nostr.wine \
  --relay wss://relay.nostr.band

Output:

Title:       Ubuntu 24.04 LTS
Event ID:    3a9f2b1c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1
Author:      npub1abc...defghijk
Info Hash:   a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0
Created:     2025-01-16T10:30:00.000Z

Description:
Official Ubuntu 24.04 LTS desktop image, amd64 architecture.

Tags:        linux, ubuntu, iso

Trackers:    wss://relay.damus.io, wss://nos.lol

Files (1):
  ubuntu-24.04-desktop-amd64.iso           1.4 GB

Magnet URI:
magnet:?xt=urn:btih:a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0&dn=Ubuntu+24.04+LTS&tr=wss%3A%2F%2Frelay.damus.io

Comments (2):
  [2025-01-17] 8f3a2b1c... — Works perfectly, seeded at 50MB/s
  [2025-01-18] d4e5f6a7... — MD5 verified, legit copy

Global Options

These apply to all commands and must be placed before the subcommand name:

Options:
  --relay <url>    Add a relay URL (repeatable, merged with defaults)
  --verbose        Enable debug logging
  --version        Print version and exit
  --help           Show help

Default relays used when none are specified:

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

Scripting Examples

# Publish and capture the nevent for sharing
NEVENT=$(tostr publish ./file.iso --title "My File" | grep "^nevent:" | awk '{print $2}')
echo "Share this: $NEVENT"

# Search and extract magnet URIs for all results
tostr search "ubuntu 24" --json | jq -r '.[].magnetUri'

# Search and pipe into a torrent client
tostr search "debian 12" --json --limit 1 \
  | jq -r '.[0].magnetUri' \
  | xargs webtorrent download

# Get the info hash of a specific event
tostr info <event-id> --json 2>/dev/null \
  | jq -r '.metadata.infoHash'

Note: info --json is not yet supported; pipe search --json and filter by event ID instead, or use the Nostr event ID directly with a relay query tool.