CLI Reference
Every Kunai launch flag, bootstrap flow, and mpv option, synced directly from the CLI help text so the table never drifts from the binary you actually run.
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.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 (Node launcher; no Bun required) |
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 doctor --strict | Exit non-zero on any warning, for scripts |
kunai uninstall | Ownership-aware removal |
kunai uninstall --purge | Also delete config/history/cache |
kunai diagnostics recent | Print recent redacted diagnostics from the cache DB |
kunai diagnostics recent
Prints the most recent diagnostic events Kunai recorded locally, already redacted, without launching the shell. Useful when attaching evidence to an issue.
kunai diagnostics recent # readable output, most recent first
kunai diagnostics recent --format jsonl # one JSON object per line
kunai diagnostics recent --format markdown # human-readable table
kunai diagnostics recent --limit 50 # cap how many events print
kunai diagnostics recent --no-color # readable output without colour--format accepts pretty, jsonl, or markdown. Without --format, Kunai
prints the readable pretty output to a terminal and jsonl when the output is
piped or redirected, so kunai diagnostics recent > report.jsonl and
kunai diagnostics recent | jq behave exactly as before.
Colour follows the terminal and turns off under NO_COLOR or --no-color. Use
--color to keep it through a pipe.
To stay readable, pretty shortens very long context values and says how much it
left out. --format jsonl and --format markdown always print them in full.
Events come from the local cache database; nothing is uploaded.
Shell completions
kunai completion <shell> prints a completion script for bash, zsh, fish,
or powershell. Completions cover every flag the parser accepts and every
maintenance subcommand.
| Shell | Install |
|---|---|
| bash | kunai completion bash > /etc/bash_completion.d/kunai |
| zsh | kunai completion zsh > "${fpath[1]}/_kunai" |
| fish | kunai completion fish > ~/.config/fish/completions/kunai.fish |
| PowerShell | kunai completion powershell >> $PROFILE |
For a quick trial without installing, evaluate it in the current session;
eval "$(kunai completion bash)" (bash/zsh), or
kunai completion powershell | Out-String | Invoke-Expression.
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 a known id:
-i/--idskips the initial title search for that id. A bare ortmdb:<id>id needs-t movieor-t tv(tv = series) and is not supported together with anime mode (-a). Namespaced ids reuse the share-link grammar:anilist:<id>andmal:<id>imply anime mode,youtube:<id>implies YouTube mode;imdb:is rejected. - 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 an HTTPS link for current playback context |
/share --qr | Show an HTTPS QR and copy the full link |
/watch | Open HTTPS, compact, or kunai:// clipboard data |
/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 or namespaced catalog id |
| -t, --type | Content type for --id (tv = series) |
| -a, --anime | Anime mode (HiAnime default with provider fallback) |
| -y, --youtube | YouTube mode (YouTube provider) |
| --continue | Jump into Continue Watching |
| --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 |
|---|---|---|---|---|
| Videasy videasy | videasy.to | movie, series | Active | Registered movies/series adapter; source and subtitle inventory vary by title |
| VidLink vidlink | vidlink.pro | movie, series | Active | Movies and series with multi-language subtitles |
| VidRock vidrock | vidrock.net | movie, series | Active | Backup source for movies and series with direct video files |
| Rivestream rivestream | rivestream.app | movie, series | Candidate | Candidate movies/series adapter; quality varies by title |
| Movy movy | movy.sx | movie, series | Candidate | Movies and series via a multi-lane source aggregator |
| AniDB anidb | anidb.app | anime | Active | anidb.app catalog and streams — ani-cli v5's source; second in the default anime order |
| AllManga allanime | mkissa.to | anime | Active | Anime episodes in sub and dub — the ani-cli parity source, third in the default order |
| HiAnime hianime | hianime.at | anime | Production | Anime episodes in sub and dub via HiAnime (ani-cli parity lane) |
| Miruro miruro | www.miruro.bz | anime | Active | Primary anime source — sub and dub from many backends behind one AniList-keyed pipe |
| AnimeGG animegg | www.animegg.org | anime | Active | Independent anime source — direct MP4s, sub and dub, no AniList dependency |
| KickAssAnime kickassanime | kaa.lt | anime | Active | Independent anime source — HLS with separate subtitle tracks, sub and dub |
| YouTube 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 Oct 2, 2026, 9:34 AM UTC · source 9ce38f1ee10c. Run bun run --cwd apps/docs generate after registry changes. Docs maintenance
Last updated on