What You Can Do
A capability map of Kunai — search, play, recover, continue, discover, offline, and diagnostics.
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 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.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 / quality / subtitles | k or /source |
| Next / previous episode | n / p |
| Queue for offline | d or /download |
| 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.
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 kunai:// URLs with /share or mpv Ctrl+Shift+S. Open them with /watch, kunai --open, or the optional OS protocol handler.
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