Feature Tour
Every Kunai capability — what works, what is experimental, and what the shell can do.
Kunai is a terminal-first media shell. It resolves media streams from third-party
providers, hands playback to mpv, and keeps recovery, offline, and diagnostics
in the same session.
Who this is for: users who want a capability map with live command and provider tables.
You will learn: launch entry points, shell commands, registered providers, and what is stable vs experimental in the current beta.
Launch entry points
Common launch patterns. For the full flag list synced from kunai --help, see
CLI reference.
| Invocation | What it does |
|---|---|
kunai | Open the shell — search, browse, or pick from history |
kunai -S "Title" | Search and show results |
kunai -S "Title" --jump 1 | Search, auto-select first result |
kunai -S "Title" -q | Quick mode — same as --jump 1 with search |
kunai -a -S "Anime" | Anime mode (anime providers) |
kunai -i 438631 -t movie | Open a specific TMDB ID directly |
kunai --continue | Jump to the newest unfinished history entry |
kunai --history | Open watch history first |
kunai --offline | Open completed offline library first |
kunai --discover | Open recommendations first |
kunai --calendar | Open release calendar first |
kunai --random | Open random picks tray first |
kunai --open <url> | Play a shared kunai:// link (trusted launch) |
kunai --setup | Run setup wizard |
kunai --download -S "Title" | Download-only flow for a title (no shell queue UI) |
kunai --zen | Minimal chrome mode |
kunai --debug | Verbose logging to ./logs.txt |
Download vs queue
kunai --download(with-Sor-i) — bootstrap a title, run downloads, exit./downloadsin the shell — manage the download queue while the shell is open./downloadduring playback — queue the current item for offline.
Shell commands
Press / to open the context-aware command palette. The table below is generated
from the CLI command registry — it updates when you run bun run --cwd apps/docs generate.
| Command | Label | Aliases | Description |
|---|---|---|---|
| /setup | Setup Wizard | setup, onboarding, wizard | Configure downloads and offline defaults |
| /download | Download | download, save | Queue the selected title for offline download |
| /downloads | Download Queue | downloads, download-jobs, jobs | Inspect active, queued, and failed download jobs |
| /library | Library | library, offline, offline-library, my-downloads | Browse offline library and manage downloads |
| /search | Search | search, find | Start a new search |
| /filters | Filters | filters, advanced-search, filter | Show supported search filter syntax |
| /trending | Trending | trending, popular | Load the cached trending discovery list |
| /recommendation | Recommendations | recommendation, recommendations, recs, suggest, discover | Personalized recommendations and discovery |
| /calendar | Release Calendar | calendar, schedule, airing, today, releases | Anime and series release schedule |
| /anime-calendar | Anime Calendar | anime-calendar, anime-schedule, anime-airing | Release schedule filtered to anime |
| /series-calendar | Series Calendar | series-calendar, tv-calendar, series-schedule | Release schedule filtered to series |
| /random | Random Picks | random, roulette, spin, pick-for-me | Random recommendation tray without autoplay |
| /surprise | Surprise Me | surprise, surprise-me, recommend-me | Surprise pick without autoplay |
| /settings | Settings | settings, config, prefs | Open settings (relay, playback, shell, and more) |
| /providers | Providers | providers, provider-settings, default-provider | Switch the session provider or set defaults and priority |
| /presence | Discord Presence | presence, discord, rpc, rich-presence | Open settings for Discord Rich Presence setup and status |
| /analytics | Analytics | analytics, telemetry | Anonymous usage ping — status, payload, and consent |
| /analytics-show | Analytics payload | analytics show, analytics-show, telemetry show, telemetry-show | Print the exact JSON that would be sent |
| /notifications | Notifications | notifications, inbox, alerts | Review actionable app notices and recoverable queues |
| /toggle-mode | Toggle Mode | mode, toggle-mode | Cycle catalog mode: series, anime, then YouTube |
| /series-mode | Series Mode | series-mode, series, tv-mode | Switch into series and movies mode |
| /anime-mode | Anime Mode | anime-mode, anime | Switch into anime mode |
| /youtube-mode | YouTube Mode | youtube-mode, youtube, yt | Switch into YouTube mode |
| /quit | Quit | quit, exit, q | Exit Kunai |
| /provider | Providers | provider, switch-provider | Open the providers hub (or tracks provider section while playing) |
| /continue | Continue Watching | continue, c | Open unfinished and recent watch progress |
| /history | History | history, resume, recent | Open watch history |
| /details | Details | details, detail, overview, info | Open the expanded title overview |
| /diagnostics | Diagnostics | diagnostics, logs, debug | Open diagnostics |
| /docs | Docs | docs, documentation, guide, manual | Open Kunai documentation |
| /help | Help | help, shortcuts, ? | Show shortcuts and command help |
| /menu | Title Control Menu | menu, title-control, title-menu | Open the unified title control menu |
| /about | About | about, version | Show version and capability information |
| /update | Update | update, upgrade, check-update, version-check | Check for a new Kunai version and show safe update guidance |
| /image-pane | Image Pane | image, preview, poster | Toggle the image and details companion pane |
| /toggle-autoplay | Pause Autoplay | autoplay, pause-autoplay, resume-autoplay | Temporarily pause or resume autoplay for this playback chain |
| /toggle-autoskip | Pause Autoskip | autoskip, skip, pause-autoskip, resume-autoskip | Temporarily pause or resume auto-skip for this session |
| /stop-after-current | Stop After Current | stop-after, stop-after-current, one-more, finish-episode | Stop after current episode instead of continuing |
| /replay | Replay | replay, restart | Restart the current item from the beginning without refreshing the source |
| /recover | Recover Playback | recover, fix, repair, retry-playback | Refresh the current stream and resume this episode after a playback issue |
| /recompute | Recompute Sources | recompute, refresh-sources, force-refresh, bypass-cache, ignore-cache, all-sources, all-servers, probe-sources | Re-resolve on the current provider only: bypass stream cache and provider memory, then probe all VidKing sources |
| /fallback | Fallback Provider | fallback, try-next-provider, next-provider, f | Stop waiting on the current provider and try the next compatible provider |
| /play-local | Play Downloaded Copy | play-local, local, offline-play, play-offline | Switch the current episode to the verified offline download |
| /watch-online | Watch Online | watch-online, online, stream-online | Switch the current episode back to online provider streaming |
| /source | Source / Servers | source, sources, mirror, server, servers, tracks | Open the tracks panel at the source / servers section |
| /quality | Quality | quality, qualities, variant | Open the tracks panel at the quality section |
| /audio | Audio | audio, dub, language | Open the tracks panel at the audio section |
| /subtitle | Subtitles | subtitle, subtitles, subs, captions, cc | Open the tracks panel at the subtitles section |
| /memory | Memory | memory, mem | Temporarily show runtime memory usage |
| /mark-anime | Mark as Anime | mark-anime, set-anime, is-anime | Reclassify the current title as anime in your history (fixes a wrong label) |
| /mark-series | Mark as Series | mark-series, set-series, not-anime | Reclassify the current title as series in your history (fixes a wrong label) |
| /share | Share This | share, share-link, share-code | Copy a catalog-anchored kunai:// share link for the current title |
| /bookmark | Bookmark Current | bookmark, bookmarks-add, save-current, watchlist-add | Save or unsave the current title in your watchlist |
| /follow | Follow Releases | follow, track, track-releases | Track future releases and notices for the current title |
| /unfollow | Unfollow Releases | unfollow, untrack, stop-following | Stop explicit release tracking without muting the title |
| /mute | Mute Releases | mute, mute-title, mute-releases, hide-releases | Stop release notices for the current title |
| /mark-watched | Mark Watched | mark-watched, watched, complete, finish | Mark the current movie or episode as fully watched |
| /mark-unwatched | Mark Unwatched | mark-unwatched, unwatched, unwatch | Clear the watched flag while keeping resume position |
| /mark-season-watched | Mark Season Watched | mark-season-watched, season-watched, mark-season | Mark every episode in the current season up to the current episode as watched |
| /mark-up-to-episode | Mark Up To Episode | mark-up-to-episode, mark-through, mark-through-episode | Pick an episode and mark the whole season through that episode as watched |
| /watch | Watch a Shared Code | watch, open-share, open-link | Open a kunai:// share link from your clipboard |
| /pick-episode | Pick Episode | episode, pick-episode, episodes | Open the episode picker |
| /next | Next Episode | next, n | Advance to the next episode |
| /previous | Previous Episode | previous, prev, p | Go to the previous episode |
| /next-season | Next Season | season, next-season | Jump to the next season |
| /clear-cache | Clear Cache | clear-cache, purge-cache, flush-cache | Clear stream URL cache (and optionally provider failure memory) |
| /reset-provider-health | Reset Provider Health | reset-provider-health, clear-provider-memory, forget-provider-failures | Forget provider failures so auto-fallback can retry down providers |
| /clear-history | Clear History | clear-history, reset-history, wipe-history | Remove all watch history and progress |
| /export-diagnostics | Export Diagnostics | export-diagnostics, export-logs, diag-export | Export recent diagnostics to a redacted JSON file |
| /report-issue | Report Issue | report-issue, issue, bug-report | Open the GitHub issue page with diagnostics guidance |
| /watchlist | Watchlist | watchlist, wl, watch-list, watch-later, bookmarks | View and manage the built-in Watchlist |
| /favorites | Favorites | fav, favs, favorites | View your favorite titles |
| /playlists | Playlists | playlists, playlist, pl, lists | View and manage durable playlists |
| /up-next | Up Next | up-next, upnext, queue, queue-playlist | View and manage the current playback order |
| /playlist-add | Add to Up Next | playlist-add, pl-add, add-to-up-next, queue-add, add-to-queue | Add the current title to Up Next |
| /queue-season | Queue Rest of Season | queue-season, season-queue, queue-rest-season | Queue remaining episodes in the current season |
| /stats | Stats | stats, statistics, watch-stats | Watch stats, streak, and top shows |
| /sync | Sync | sync, sync-settings, integrations | Experimental AniList progress and tracker list sync |
| /sync-connect-anilist | Connect AniList | connect-anilist, anilist-connect, anilist | Link your AniList account to sync watch progress |
| /sync-connect-tmdb | Connect TMDB | connect-tmdb, tmdb-connect, tmdb | Link your TMDB account to sync watchlist and favourites |
| /sync-disconnect | Disconnect Sync | sync-disconnect, disconnect-sync, unlink-sync | Remove linked sync accounts |
81 shell commands registered in the CLI.
Active providers
Live registry — same table as Providers. Provider names link to per-provider notes.
| Provider | Domain | Media | Status | Description |
|---|---|---|---|---|
| Videasyrecommended videasy | videasy.to | movie, series | Active | Fast direct streams with source selection and subtitles |
| VidLinkrecommended vidlink | vidlink.pro | movie, series | Active | Movies and series with multi-language subtitles |
| Rivestreamrecommended rivestream | rivestream.app | movie, series | Candidate | Beta movies/series source — recommended default, quality can vary by title |
| AniDBrecommended anidb | anidb.app | anime | Active | Anime streams via anidb.app — ani-cli v5 primary source |
| AllManga allanime | allmanga.to | anime | Active | Anime episodes in sub and dub — the primary anime source |
| Miruro miruro | www.miruro.bz | anime | Candidate | Alternate anime source — useful when a title is missing elsewhere |
| YouTuberecommended youtube | youtube.com | video | Production | YouTube via Invidious search and yt-dlp playback |
Providers not in the production engine
- Cineby — Videasy flavor research module; not registered in the CLI container.
- VidKing — legacy config/cache alias for Videasy. Do not use in new code.
What works well
- Search by title with TMDB-backed metadata
- Movie and series playback through Videasy, VidLink, and Rivestream (candidate)
- Anime playback through AniDB by default, with the AllManga-compatible
allanimeprovider as fallback and Miruro manually selectable - YouTube mode via Invidious search and yt-dlp playback
- Watch history with resume support
- Continue Watching with unfinished/new episode detection
- Release calendar with cached schedule data
- Recommendations and discovery surfaces
- Share links (
/share,/watch,kunai --open) - Offline downloads via yt-dlp with artifact validation
- Library browsing from local SQLite
- Diagnostics panel and redacted support bundle export
- Discord Rich Presence
- AniList and TMDB sync for watch progress
- Cache-first stream resolution with health checks
- Provider fallback chain and recovery flows
- Optional user-owned provider geo relay for metadata APIs
What is experimental / candidate
- Rivestream and Miruro — candidate status in manifests; quality varies by title
- Zen mode (
--zen) — minimal chrome, still settling - Notifications inbox — active, alert delivery maturing
- Playlist queue — durable service active, multi-session recovery being validated
What is not supported
- Browser-based scraping (Playwright) — archive-only reference
- Kunai-hosted cloud proxy infrastructure for video streams
- First-party streaming service authentication
- Content hosting or redistribution
- Native GUI outside the terminal
- Native app store packages (use
install.sh/install.ps1or package managers instead) - Silent mode-switching between online and offline
- Stream URLs in unredacted support bundles
Hotkeys
| Context | Keys | Action |
|---|---|---|
| Anywhere | / | Open command palette |
| Browse results | Tab | Cycle browse filters / content kind |
| Browse results | Shift+F | Open filters |
| Browse results | Enter | Open or play selected result |
| Browse results | Shift+Enter / i | Open title details |
| Browse results | Ctrl+F | Focus filters |
| Browse results | Ctrl+D | Queue for download |
| Browse / pickers | Esc | Clear, close, or go back |
| Playback | r | Recover current stream |
| Playback | f | Try next compatible provider |
| Playback | d | Queue for download |
| Playback | k | Open tracks/source/quality |
| Playback | n / p | Next / previous episode |
| Playback | a / u | Toggle autoplay / autoskip |
Diagnostics flow
/diagnostics → runtime panel with provider timeline
/export-diagnostics → redacted JSON bundle (no URLs, no tokens)
/report-issue → GitHub issue page with bundle guidance
--debug → verbose startup and runtime logging
--debug-json → structured JSONL event stream
--debug-session → full session traceSee Diagnostics and reporting for the user-facing guide.
Platform support
Release binaries via install.sh (Linux/macOS) and install.ps1 (Windows) embed the Bun runtime — you do not need Bun installed to run them. Linux is supported; macOS and Windows x64 are beta; Windows ARM64 is experimental. Unsigned binaries may trigger SmartScreen or Gatekeeper on first run; see Install and update. Keep installs current with kunai upgrade.
| Platform | Install | Playback | Downloads | Poster previews |
|---|---|---|---|---|
| Linux (supported) | install.sh or bun/npm global | mpv | yt-dlp + ffprobe | Kitty / iTerm2 / Sixel / half-block (no install) |
| macOS (beta) | install.sh or bun/npm global | mpv | yt-dlp + ffprobe | iTerm2 / Sixel / half-block (no install) |
| Windows x64 (beta) | install.ps1 or bun/npm global | mpv | yt-dlp | iTerm2 / Sixel / half-block (no install) |
| Windows ARM64 (experimental) | install.ps1 | mpv | yt-dlp | iTerm2 / Sixel / half-block (no install) |
Storage architecture
| Store | Type | Contents |
|---|---|---|
| Config | JSON | ~/.config/kunai/config.json, provider overrides |
| Data DB | SQLite | History, lists, playlists, notifications, downloads |
| Cache DB | SQLite | Stream URLs, provider health, schedules |
| Logs | File | ./logs.txt when --debug is enabled |
Command and provider tables on this page are generated from the Kunai CLI (v0.3.0) at Aug 18, 2026, 2:47 PM UTC · source ade6600a. Run bun run --cwd apps/docs generate after registry changes. Docs maintenance
Edit on GitHub
Last updated on