Getting Started
Install Kunai, verify dependencies, and complete your first playback session with explicit recovery steps.
Kunai is a terminal-first media shell. You search for a title, pick what to watch, Kunai resolves a direct-provider stream on your machine, and hands playback to mpv. The shell stays alive so you can recover, continue, or pick something else without restarting.
Who this is for: anyone installing Kunai for the first time.
You will learn: how to install, launch your first search, use high-signal shell commands, and recover when playback fails.
Beta scope (read this first)
install.sh / install.ps1 (self-contained binary — Bun runtime embedded; you do not need Bun). Bun/npm globals are secondary; npm requires Bun on PATH. You still need mpv for playback — setup and browsing work without it. Kunai does not host media - it resolves streams from third-party providers on your machine and hands playback to mpv. Provider availability changes; recovery commands exist because drift is expected.Quick start
Install the binary
Preferred path (self-contained binary — no Bun or Node required). Bootstrap script differs by OS:
# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/KitsuneKode/kunai/main/install.sh | bash
# Windows (PowerShell)
irm https://raw.githubusercontent.com/KitsuneKode/kunai/main/install.ps1 | iex
kunai --versionBun/npm globals and source checkouts are secondary. See Install and update for those channels.
Confirm mpv, then run setup
Playback needs mpv on your PATH. Setup and browsing still work when mpv is missing — only committed playback startup requires it.
mpv --version
kunai --setupSearch and pick a title
Start with kunai -S "Dune". Select a result, choose an episode when needed, let Kunai resolve a provider stream, then confirm mpv startup. Search shows results — it does not auto-play unless you add --jump or -q.
Learn recovery early
Press / for the palette. If playback stalls: /recover refreshes the current provider, /fallback tries the next compatible provider, /diagnostics shows evidence.
The preferred path installs a self-contained binary — you do not need Bun. Confirm the install, check mpv, run setup, then search:
curl -fsSL https://raw.githubusercontent.com/KitsuneKode/kunai/main/install.sh | bash
kunai --version
mpv --version
kunai --setup
kunai -S "Dune"-S opens search results. Select a title, pick an episode when prompted, wait for provider resolution, then confirm the committed mpv startup. If mpv is missing, setup and browsing stay available — only playback handoff is blocked.
Other install methods
Use these tabs only when you need a different channel. Source checkout is contributor-oriented.
npm install -g @kitsunekode/kunai
kunai --setupnpm global installs require Bun on your PATH (the published package starts with #!/usr/bin/env bun). Postinstall writes ownership into install.json so kunai upgrade / kunai uninstall route correctly. Diagnose PATH and ownership with kunai doctor.
bun install -g @kitsunekode/kunai
kunai --setupgit clone https://github.com/KitsuneKode/kunai.git
cd kunai
bun install
bun run link:global
kunai --setupUse bun run dev -- <flags> when you need to forward argv without a global link. Prefer this path for contributors debugging providers or docs — not for day-to-day watching.
Launch recipes
Four common first-week patterns. Full flag list: CLI reference.
First play (search, then pick)
kunai -S "Dune"-S opens search results — it does not auto-play. Add --jump 1 or -q when you want the first match selected automatically.
Anime mode
kunai -a -S "Attack on Titan" --jump 1Continue where you left off
kunai --continueUse --history when you want to pick from recent entries instead of the newest unfinished one.
Offline library
kunai --offline--zen --offline keeps chrome minimal over the same library. Download-only bootstrap: kunai --download -S "Title" (resolve, queue, exit).
Search does not mean auto-play
-S "Title" lands on results. Discovery trays (--discover, --random, --calendar) also open without auto-play.
Two download entry points
kunai --download -S "Title" is a download-only bootstrap: resolve the title, queue downloads, exit - no shell queue UI. /downloads inside the running shell manages queued, running, and failed jobs. Do not confuse them.In the shell
Press / to open the command palette. High-signal commands for a first week:
| Command | Purpose |
|---|---|
/history | Recent watch progress |
/up-next | Current playback order |
/downloads | Queued, running, and failed download jobs |
/library or /offline | Playable completed downloads |
/diagnostics | Runtime state and recent evidence |
/update | Manual version check (kunai upgrade is the primary update path) |
/recover | Refresh the current stream after failure evidence |
/fallback | Try the next compatible provider |
Browse mode uses Tab to cycle content filters; Shift+F opens the public filter surface when available.
When playback fails
Stay in the shell
Do not restart blindly. Kunai keeps session context, provider inventory, and local watch history.
Recover, then fallback
Run /recover to refresh the current provider intent. If that fails, /fallback walks the priority chain.
Read evidence
Open /diagnostics. For a shareable bundle use /export-diagnostics — exports are redacted by default.
Next reads
- Platforms for OS-specific optional tools
- CLI reference for launch flags and provider tables synced from the CLI
- Providers for fallback chains and per-provider notes
- Playback and recovery for the full failure playbook
Last updated on