Getting Started
Install Kunai, put it on your PATH, install mpv, run setup, and complete a first playback session end to end, with the exact commands for your platform.
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.
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 needs Node on PATH, not Bun. You still need mpv for playback; setup and browsing work without it. Kunai is a client-side playback tool. It does not host, upload, mirror, seed, or distribute video content. Streams and related assets are served by non-affiliated third-party providers. Use responsibly and in accordance with applicable laws and service terms. 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 / macOScurl -fsSL https://kunai.kitsunekode.in/install.sh | bash# Windows (PowerShell)irm https://kunai.kitsunekode.in/install.ps1 | iexkunai --versionThe Unix installer links ~/.local/bin/kunai. If that directory is not on PATH, the script prints the export to add; it does not rewrite your shell profile. Windows places the launcher under %LOCALAPPDATA%\kunai\bin. Then run kunai doctor. Bun/npm globals and source checkouts are secondary. See Install and update.
Install mpv, then run setup
Playback needs an mpv binary on the same PATH as Kunai. Setup and browsing still work when mpv is missing; only committed playback startup requires it. Kunai looks for mpv / mpv.exe, not mpvnet.exe.
# Linuxsudo pacman -S mpv # Archsudo apt install mpv # Debian/Ubuntusudo dnf install mpv # Fedora# macOSbrew install mpv# Windows: binary on PATH must be named mpv.exewinget install mpvmpv --versionkunai doctorkunai --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 or ⇧F tries the next compatible provider, /diagnostics shows evidence.
Preferred Linux/macOS bootstrap (same command the steps above use):
curl -fsSL https://kunai.kitsunekode.in/install.sh | bash
kunai --version
mpv --version
kunai --setup
kunai -S "Dune"If kunai: command not found after install, the binary is not on PATH. On Linux/macOS add ~/.local/bin (the installer prints the exact export). On Windows add %LOCALAPPDATA%\kunai\bin. Then kunai doctor.
-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 need Node on your PATH (the published bin is a Node launcher that spawns a platform binary). You do not need Bun for the npm channel. Diagnose PATH and ownership with kunai doctor.
First week in the shell
Press / for the command palette. Surfaces that matter:
| Surface | Command | Meaning |
|---|---|---|
| Watchlist | /watchlist | Built-in watch-later list |
| Playlists | /playlists | Durable named collections |
| Up Next | /up-next | Current playback order (/queue is an alias) |
| Downloads | /downloads | Queued / running / failed jobs |
| Library | /library | Completed offline titles |
| History | /history | Resume progress |
Tab cycles catalog mode (series / anime / YouTube). Ctrl+F narrows loaded results. /filters opens the public filter surface. During playback, provider fallback is ⇧F (Shift+F), not a bare f.
When playback fails
Stay in the shell. /recover refreshes the current provider. /fallback or ⇧F walks the priority chain. /diagnostics shows evidence; /export-diagnostics writes a redacted bundle.
Anime episodes that will not play, or an anime search that reports a provider unreachable rather than coming back empty, often mean curl is missing: the anime providers sit behind Cloudflare and the plain-fetch fallback gets challenged. kunai doctor reports curl. See Troubleshooting.
Next reads
- Install and update for upgrade, rollback, unsigned binaries, and PATH
- Disclaimer: Kunai is a client; it does not host content
- Platforms for OS-specific optional tools
- Providers for fallback chains and per-provider notes
- Playback and recovery for the full failure playbook
- CLI Reference for launch flags (
--continue,-a,--offline)
Last updated on
Overview
Install Kunai, operate the terminal shell, resolve third-party streams, recover when playback stalls, manage offline media, and configure it to your setup.
Install and Update
Install Kunai on Linux, macOS, or Windows via the native binary or npm, then keep it current, with upgrade, rollback, and uninstall behaviour explained.