CLI reference
Launch flags, bootstrap flows, and mpv options synced from the Kunai CLI help text.
Beta scope (read this first)
Kunai is a terminal-first CLI during beta. Preferred install is
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.Kunai is a terminal-first CLI. Most day-to-day work happens inside the interactive shell after launch — history, provider pickers, recovery, and diagnostics are shell commands, not separate argv flags.
This page lists process flags parsed from kunai --help. For shell commands, see
Commands and shortcuts or the generated command table
on the Feature tour.
Install and run
| Command | When to use |
|---|---|
curl … | bash (install.sh) | Preferred end-user install (binary; no Bun required) |
npm install -g @kitsunekode/kunai | npm channel (requires Bun on PATH) |
bun install -g @kitsunekode/kunai | Bun global channel |
kunai | Open the interactive shell |
kunai -S "Title" | Bootstrap with a search query |
kunai -i 438631 -t movie | Open a known TMDB id (non-anime) |
kunai -a -S "Anime" | Anime mode with bootstrap search |
From a repo clone (contributor-oriented), use bun run dev -- <flags> so Bun forwards argv to the CLI.
Lifecycle maintenance
| Command | What it does |
|---|---|
kunai install | Install or reinstall (binary default) |
kunai upgrade | Primary channel-aware update |
kunai upgrade --check | Report whether an update is available |
kunai rollback | Roll back to the previous verified local version |
kunai rollback --list | List local verified rollback candidates |
kunai rollback --to <ver> | Roll back to an explicit verified version |
kunai doctor | Read-only install health (PATH, ownership) |
kunai doctor --json | Same report as JSON |
kunai uninstall | Ownership-aware removal |
kunai uninstall --purge | Also delete config/history/cache |
Launch flows
- Interactive — no bootstrap flags: the Ink shell opens and you search or pick from history.
- Bootstrap search —
-S/--search: runs the first search and lands on results. Does not auto-play unless you add--jumpor--quick. - Bootstrap TMDB title —
-i/--idwith-t movieor-t tv(tv = series): skips the initial title search for that id. Not supported together with anime mode (-a). - Anime mode —
-a/--anime: anime discovery and providers. - Continue watching —
--continue/--resume: newest unfinished local history entry. - History first —
--history: watch history picker at startup. - Offline library first —
--offline: completed downloads only (same intent as/library). - Discover / calendar / random —
--discover,--calendar,--random: open those trays first without auto-play. - Share link handoff —
--open <kunai://url>: trusted launch without protocol confirmation;--install-protocol-handlerregisters the Linux-only OS handler.
Share links
| Flag / command | What it does |
|---|---|
kunai --open "kunai://play?..." | Resolve and play a shared catalog link |
kunai --install-protocol-handler | Register kunai:// with the OS (Linux-only) |
/share | Copy link for current playback context |
/watch | Open link from clipboard |
/up-next | Current playback order |
/downloads | Download queue overlay |
/library | Offline library |
More: Share links.
Download modes (do not confuse)
| Entry | What it does |
|---|---|
kunai --download -S "Title" | Download-only launch flag. Resolves a title, then runs the download flow and exits — no interactive shell queue UI. Requires -S or -i bootstrap. |
kunai --download -i 438631 -t movie | Same download-only path with a fixed TMDB id. |
/downloads in the shell | Queue overlay while the shell is running — queued, running, and failed jobs. |
/download during playback | Queue the current item for offline from inside a session. |
Launch flags
| Flag | Description |
|---|---|
| -S, --search | Search for a title on launch |
| -i, --id | Open a specific title id |
| -t, --type | Content type for --id (tv = series) |
| -a, --anime | Anime mode (AniDB default with provider fallback) |
| -y, --youtube | YouTube mode (YouTube provider) |
| --resume | Jump into Continue Watching |
| --history | Open watch history |
| --offline | Offline library only (no provider calls) |
| --discover | Open recommendations |
| --calendar | Open the release calendar |
| --random | Open the random picks tray |
| --download | Download-only flow for a selected title (use with -S or -i; does not open the shell queue) |
| --setup | Run the setup wizard |
| -m, --minimal | Minimal chrome |
| -z, --zen | Zen mode (bare, ani-cli-style) |
| -q, --quick | Quick layout |
| --jump | Auto-pick the n-th search result (1-based, with -S) |
| --mpv-debug | Verbose mpv logging |
| --mpv-clean | Ignore your mpv config for this run |
| --no-user-mpv-config | Same, explicit |
| --mpv-log-file | Write the mpv log to a file |
| --download-path | Override the download directory |
| --open | Open a trusted kunai:// share link |
| --install-protocol-handler | Register the Linux-only kunai:// URL handler |
| --handoff-url | Internal: open a kunai:// deep link |
| --dry-run | Print what would happen, change nothing |
| --debug | Verbose redacted logging to ./logs.txt |
| --debug-json | Debug + JSON event stream |
| --debug-session | Debug + full session trace |
| --support-bundle | Write a redacted local support bundle and exit |
| -h, --help | Show this help |
| -v, --version | Print the version |
mpv and diagnostics
- mpv:
--mpv-debug,--mpv-clean,--no-user-mpv-config,--mpv-log-file <path>forward into the player for this run. - Diagnostics:
--debugwrites verbose logs to./logs.txt.--debug-jsonand--debug-sessionadd structured traces for support bundles. - Dry run:
--dry-runprints the planned bootstrap without changing state.
Providers
Production providers are registered in the CLI container and listed here for reference:
| 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 |
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