What You Can Do
A capability map of Kunai: search, play, recover, continue watching, discover, download for offline, share links, and diagnose, with the command for each.
Kunai is a terminal-first media shell. You search for a title, Kunai resolves a direct-provider stream on your machine, hands playback to mpv, and keeps the shell alive so you can recover, continue, or pick something else without restarting.
Who this is for: anyone evaluating what Kunai can do day to day.
You will learn: search, playback, recovery, continuation, discovery, offline, and diagnostics workflows in plain language.
This page is the capability narrative. For flag-level detail, see CLI Reference. For live command and provider tables, see Feature tour.
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.Search and pick
Kunai searches TMDB-backed catalogs for movies and series, and anime-specific providers when you launch in anime mode.
Open the shell and search
kunai
kunai -S "Dune"
kunai -a -S "Attack on Titan"-S runs search and lands on results. It does not auto-play unless you add --jump 1 or -q.
Bootstrap a known title
kunai -i 438631 -t movieUse TMDB ids for movies and series. Anime mode uses provider-native ids through the anime flow.
Inspect before you commit
Browse results support filters, details sheets, and provider hints before playback starts. Episode numbers in the UI are 1-based.
More: Getting started, Media selection.
Play
Playback always goes through mpv. Kunai resolves stream URLs, headers, and subtitle attachments, then supervises the player through IPC.
- Kunai does not host video files or replace
mpv. - Source, quality, audio, and subtitle pickers appear when the resolved inventory has more than one useful choice.
- Preferred language profiles differ for anime, series, and movies; see Customization.
During playback, hotkeys and commands stay available:
| Action | Keys / command |
|---|---|
| Recover current stream | r or /recover |
| Next compatible provider | ⇧F or /fallback |
| Source | o or /source |
| Quality | k |
| Next / previous episode | n / p |
| Queue for offline | /download or Ctrl+D while browsing |
| Copy share link | /share or mpv Ctrl+Shift+S |
| Open shared link | /watch or kunai --open <url> |
More: Share links, Playback and recovery, Commands and shortcuts.
YouTube mode
Tab (or -y / /youtube-mode) switches the catalog to YouTube. Search uses Invidious; playback needs yt-dlp. Results are labelled as videos, Shorts, playlists, channels, or live/upcoming entries before you open them when the selected backend provides that signal; otherwise Kunai labels them conservatively. Playlists and channels are collections; pick a video inside them. Live URLs resolve as videos. SponsorBlock categories are opt-in in Settings › YouTube. Cookies are optional and stay on your machine. Details: Providers.
Recover when streams fail
Provider catalogs drift. Recovery is normal usage, not a sign the app is broken.
Kunai separates three ideas:
- Recover: refresh the current playback intent on the active provider (new resolve evidence, cache revalidation, or mpv reload).
- Retry: provider-local cycling through sources, servers, or variants before giving up on that provider.
- Fallback provider: move to the next compatible provider in your priority list after the active provider is exhausted.
Use /diagnostics to see which path Kunai took. Recovery mode (guided, fallback-first, manual) is configurable in Settings.
More: Providers, Troubleshooting.
Continue watching
Local watch history drives resume and continue flows. Nothing is uploaded unless you opt into sync integrations.
kunai --continue
kunai --history--continueopens the newest unfinished history entry./historylets you pick any previous title manually.- Continue Watching surfaces unfinished episodes and newly released episodes when schedule data is available.
More: Continue watching and new episodes.
Share links across machines
Copy catalog-anchored HTTPS URLs with /share or mpv Ctrl+Shift+S, or show a terminal QR with /share --qr. Open HTTPS, compact, or kunai:// handoffs with /watch; kunai --open and the optional OS protocol handler remain available for application links.
More: Share links.
Discover and browse beyond search
Kunai includes recommendation and schedule surfaces that do not auto-play:
kunai --discover
kunai --calendar
kunai --random| Surface | Purpose |
|---|---|
/discover | Personalized recommendations from local history and catalog signals |
/calendar | Releases airing today with cached schedule data |
/random | Small explained surprise tray; rerollable, never auto-plays |
/recommendation | Same family as discover from the command palette |
Discover mode policy (auto, unified, anime-only, series-only) is configurable. See Customization.
Offline library and downloads
Downloads are opt-in and local-first. Completed artifacts live on disk; the offline library reads SQLite and filesystem facts only.
kunai --offline
kunai --zen --offline/downloads: active queue (queued, running, failed jobs)./libraryor/offline: completed local media ready to play.kunai --download -S "Title": download-only launch path (no shell queue UI).
Opening the offline library never calls providers. Repair and re-download are explicit user actions.
More: Downloads and offline.
Diagnostics and support
Diagnostics are local-first and redacted by default.
/diagnostics
/export-diagnostics
/report-issue/diagnostics: runtime panel with provider timeline, cache provenance, mpv state, and network snapshot./export-diagnostics: redacted JSON bundle (no stream URLs, tokens, or private paths).--debug,--debug-json,--debug-session: verbose logging and structured traces for deeper investigation.
Review exported bundles before sharing publicly.
More: Diagnostics and reporting, Reliability and privacy.
What Kunai does not do
Kunai does not host streams, mirror content, or guarantee third-party catalog stability. Browser-based scraping (Playwright) is archive-only reference, not part of the active beta runtime.
See Supported and Unsupported for the full matrix.
Related guides
| I want to… | Start here |
|---|---|
| Install and verify dependencies | Getting started |
| Tune providers and mpv | Customization |
| Fix a specific failure | Troubleshooting |
| Understand provider fallback | Providers |
| Know beta boundaries | Supported and unsupported |
Last updated on
Supported and Unsupported
What Kunai supports during beta, what is experimental and may change, and what is explicitly unsupported, so you know what to rely on before you install.
Feature Tour
Every Kunai capability in one place: what is shipped, what is experimental, and what is explicitly out of scope, with the shell commands that reach each one.