🍿 popcorn-cli

One command. Stream anything. From your terminal.

Remember Popcorn Time? This is that, but for your terminal. One command. No Electron. No bloat. AI-agent ready. Search, stream, cast — with subtitles — in a single pipeline that machines and humans both love.

CLI	TUI

---

Quick Start

make install                           # install to ~/.local/bin
pop play "blade runner" --lang es      # search → pick stream → find subs → play
pop tui                                # or launch the cinematic TUI

That's it. One command finds the torrent, selects the best stream, grabs subtitles, and casts to your Chromecast or VLC.

---

Why popcorn-cli?

• 🎯 One-command magic — pop play "movie name" handles search → stream selection → subtitles → playback. No manual steps.
• 🤖 AI-native JSON API — Every command speaks --json with structured output, exit codes, and deterministic fields. Built for agents first.
• 🖥️ Beautiful TUI — Cinematic two-pane interface with keyboard navigation and command palette. For when you want to browse.
• 🌍 Cross-platform — macOS, Linux, Windows. Single binary, zero runtime deps.
• 📐 Smart stream selection — Auto-picks streams ≤1.5GB (configurable), enforces hard cap at 3GB. Exposes ranked options so agents can reason about seeders and size.
• 🗣️ Subtitle magic — Auto-download, health analysis, sync offset control, cached by IMDB ID + language + release hash for stable reuse.
• 📺 Chromecast + VLC — Cast to any local Chromecast or play in VLC. Device caching means zero prompts after first use.

---

Feature Showcase

🔍 Discover

pop --json search "blade runner"
pop --json trending
pop --json info 550 --type movie

📡 Streams & Subtitles

pop --json streams tt1877830 --limit 5
pop --json subtitles tt1877830 --lang es --limit 5
pop --json subtitle-health /path/to/subtitles.srt --sample 5

▶️ Playback

# The all-in-one command — search, stream, subtitle, play
pop --json play "the batman" --lang es
pop --json play "the batman" --result-index 1 --lang es --vlc
pop --json play "bone temple" --lang es --subtitle-index 1 --vlc

# Cast by IMDB ID
pop --json cast tt1877830
pop --json cast tt1877830 --max-size-gb 1
pop --json cast tt1877830 --dry-run

# Cast a magnet directly
pop --json cast-magnet "magnet:?xt=urn:btih:..." --lang es --imdb tt1877830 --subtitle-index 0 --device "Cuarto de estar"

# Local playback
pop --json play-local "the batman" --lang es

🎛️ Playback Controls

pop --json status
pop --json pause
pop --json stop
pop --json seek +30
pop --json volume 80

🗣️ Subtitle Sync

pop --json subsync +1.5          # shift subs forward 1.5s (applies on next launch)
pop --json subsync status
pop --json subsync reset

📺 Devices

pop --json devices refresh
pop --json devices default auto
pop --json devices default set "Cuarto de estar"

🔧 System

pop --json doctor
pop --json config get
pop --json config set lang es
pop --json config set target-size-gb 1.5
pop --json config set max-size-gb 3

---

For AI Agents

This is what makes popcorn-cli different. Every command is a stable JSON contract designed for machine consumption.

pop --json play "inception" --lang es

{
  "selected_match": { "title": "Inception", "imdb_id": "tt1375666" },
  "selected_stream": { "seeders": 450, "size_gb": 1.2 },
  "selected_subtitle": { "language": "es", "release_hash": "..." },
  "subtitle_asset": "/path/to/cached/subtitle.srt",
  "subtitle_attached": true,
  "match_options": [ "..." ],
  "selected_match_index": 0
}

What agents get:

• Structured JSON on every command via --json — no screen-scraping
• Ranked options — cast and play return the full stream options list with selected_stream and selected_index
• Disambiguation — --result-index for search results, --subtitle-index for subtitle candidates
• Dry runs — --dry-run previews selection without launching playback
• Deterministic exit codes — success, not-found, playback-error
• Zero interaction — device caching + smart defaults = no prompts

Full contract: docs/cli-contract.md

---

TUI

Launch with pop tui. Keyboard-first, cinematic two-pane interface with command palette (Ctrl+K).

Workspaces: Discover · Streams · Subtitles · Playback · Devices · Tools

Uses an in-process command gateway with the same semantics as the JSON CLI — everything you can script, you can browse.

---

Installation

From source (recommended)

git clone https://github.com/spanishflu-est1918/popcorn-cli && cd popcorn-cli
make install    # installs `pop` to ~/.local/bin (override with PREFIX=/your/path)

Go install

go install github.com/spanishflu-est1918/popcorn-cli/cmd/pop@latest

Pre-built binaries

make release    # builds cross-platform artifacts in dist/

Development

go run ./cmd/pop --json search "test"
make test
make build

---

Configuration

pop --json config get                    # show all settings
pop --json config set lang es            # default subtitle language
pop --json config set target-size-gb 1.5 # preferred stream size
pop --json config set max-size-gb 3      # hard size cap

Environment overrides: POP_TARGET_SIZE_GB, POP_MAX_SIZE_GB, POP_VLC_BIN (custom VLC path).

VLC is auto-detected from PATH and common macOS app paths.

---

Contributing

PRs welcome. Run make test before submitting. The JSON CLI contract in docs/cli-contract.md is the stable API surface — don't break it.

---

Architecture

Modular monolith:

Package	Role
cmd/pop	CLI entrypoint
internal/cli	Argument parsing + output formatting
internal/app	Use-case orchestration
internal/domain	Core types and rules
internal/providers	External metadata/stream/subtitle providers
internal/cache	Cache and persistence
internal/tui	Bubble Tea TUI
test/e2e	End-to-end tests with fake binaries

---

The spiritual successor to Popcorn Time. For terminals. For agents. For the love of movies.