streamnet-cli

Torrent search → in-process WebTorrent streaming → native VLC, with hash-based subtitles.

Replaces the fragile .torrent → Stremio → VLC → VLSub pipeline with a single, scriptable command. No GUI. No Flatpak. No legacy dependency chain.

Why

Eduardo ran a manual streaming pipeline for years: download a .torrent, open it in the Stremio GUI, pipe it to VLC, fetch subtitles with VLSub. The migration to Pop!_OS broke it repeatedly — libmpv1 removed in Ubuntu 24.04, libssl1.1 vs OpenSSL 3, and Flatpak sandboxing that silently broke IPC between Stremio and VLC.

StreamNet owns the entire pipeline in Node.js so none of that can break:

streamnet play "Blade Runner 2049"
  → search indexers → rank by health (MKV first) → pick best torrent
  → stream via WebTorrent (no full download) → spawn native VLC
  → if not MKV: fetch subtitles by file hash → load in VLC

Agent-native by design

Like gh and vercel, StreamNet is a first-class tool for both humans and terminal AI agents (Claude Code, Codex, Gemini CLI, Hermes, OpenClaw, OpenCode, DeepSeek) on Linux, macOS, and Windows:

• --json on every command — stable, versioned, machine-readable envelopes
• --yes skips all prompts; --no-input forbids them (exit 77 instead)
• Deterministic POSIX exit codes you can branch on
• stdin/stdout composability — streamnet search … --json | jq … | streamnet stream -
• streamnet manifest — enumerate every command, flag, exit code, and schema
• streamnet mcp — an MCP server so any agent can call commands (v0.4)
• Zero hidden TTY requirements in agent mode

Install

# npm (primary — requires Node.js >= 20)
npm install -g streamnet-cli

# or grab a standalone binary (no Node required)
# https://github.com/aedneth/streamnet-cli/releases

Then install native VLC and verify:

streamnet setup     # installs native VLC for your OS (never Flatpak/Snap)
streamnet doctor    # verifies VLC, webtorrent, Node, network

Usage

streamnet search "Blade Runner 2049"          # health-ranked results
streamnet play   "Blade Runner 2049" --yes    # search + best result + stream
streamnet stream "magnet:?xt=urn:btih:..."     # stream a specific torrent
streamnet config list                          # view configuration
streamnet manifest                             # machine-readable command catalog

Agent / scripting examples

# Pure JSON, no prompts, scriptable exit codes
streamnet play "Sintel" --yes --json

# Pipe a magnet from another tool
echo "$MAGNET" | streamnet stream - --no-subs --json

# Branch on exit code
streamnet search "obscure title" --json || case $? in
  3) echo "no results" ;;
  5) echo "network down" ;;
esac

Demo

$ streamnet play "Blade Runner 2049" --yes
  Searching 2 indexers... done (14 results)
  Ranking by health: MKV-first, seeders, ratio
  ✔ Selected  Blade.Runner.2049.2017.2160p.UHD.BluRay.MKV  ▸  1847 seeders
  Streaming   magnet:?xt=urn:btih:a3f1… → localhost:38427
  ✔ Launched  VLC (/usr/bin/vlc) with stream URL
  ✔ Subtitles not needed — MKV has embedded English track

$ streamnet search "Dune 2" --json | jq '.data[0] | {title, seeders, container}'
{
  "title": "Dune.Part.Two.2024.2160p.UHD.BluRay.MKV",
  "seeders": 3241,
  "container": "mkv"
}

$ streamnet doctor --json | jq '.data.allOk'
true

Exit codes

| Code | Name | Meaning | | ---: | ------------------ | ------------------------------------------- | | 0 | OK | Success | | 1 | ERROR | Generic/unexpected error | | 2 | USAGE | Invalid arguments or flags | | 3 | NO_RESULTS | Search returned nothing | | 4 | DEP_MISSING | Required dependency (VLC) not found | | 5 | NETWORK | Indexer/API/network failure | | 6 | TORRENT_UNPLAYABLE | No peers / metadata timeout | | 7 | PLAYER_FAILED | VLC failed to spawn or crashed | | 8 | SUBS_NOT_FOUND | No matching subtitles | | 9 | CONFIG | Invalid/unwritable config | | 10 | AUTH | OpenSubtitles auth/rate-limit | | 77 | EX_NOINPUT | Prompt needed but running non-interactively | | 130 | SIGINT | Interrupted |

Configuration

Config lives under XDG paths (~/.config/streamnet/config.json on Linux/macOS, %APPDATA%\streamnet on Windows). Manage it with streamnet config:

streamnet config set minSeeders 5
streamnet config set preferredContainers mkv,mp4
streamnet config get opensubtitles.apiKey   # secrets are redacted on display

Roadmap

| Version | Status | Highlights | | ------- | ------ | ---------- | | v0.1.0 | ✅ shipped | Search (torrents-csv + YTS), WebTorrent engine, native VLC spawn, setup/doctor, agent-native --json / exit codes / manifest | | v0.2.0 | planned | OpenSubtitles hash-based subtitle fetch + VLC injection; MCP server (streamnet mcp) | | v0.3.0 | planned | Real-debrid / Premiumize resolver; additional indexers (1337x, RARBG mirrors) | | v0.4.0 | planned | Watch history + resume; streamnet library catalog; shell completions | | v1.0.0 | future | Stable public API, binary releases, Homebrew tap, Scoop bucket |

Contributing

Bug reports, feature requests, and PRs are welcome. Please read CONTRIBUTING.md before opening an issue or pull request.

License — AGPL-3.0 + Dual Commercial (final)

StreamNet CLI is dual-licensed:

• Open source & free for the public under the GNU AGPL-3.0 — see LICENSE.
• Commercial licenses are sold separately for organizations that need to integrate StreamNet into proprietary products without AGPL obligations — see LICENSE-COMMERCIAL.

MIT and Apache are intentionally rejected: they would let a company use and resell this work without a commercial agreement. The AGPL keeps the public version free and open, while reserving a commercial path for those who need it.

Commercial licensing: [email protected]

Part of the Korvex agent-native developer-tool suite.