Platforms

Kunai is terminal-first. Playback uses mpv; optional downloads use yt-dlp; ffprobe can validate completed artifacts when available. Poster previews need nothing installed: Kitty graphics on Kitty/Ghostty, iTerm2 inline images on iTerm2 and VSCode 1.80+, sixel where the terminal reports it, and a built-in half-block fallback everywhere else.

Who this is for: anyone choosing an install path or optional tools for their OS.

You will learn: recommended installers per platform, optional dependencies, and platform-specific handoff behavior.

Support posture (0.3.0)Copy Anchor Link

kunai:// protocol registration is Linux-only in 0.3.0 (including WSL). macOS/Windows can still use kunai --open without OS handler registration.

curl -fsSL https://kunai.kitsunekode.in/install.sh | bash
kunai --version
mpv --version
kunai --setup

# npm — Node launcher, no Bun
npm install -g @kitsunekode/kunai
# bun global — needs Bun on PATH
bun install -g @kitsunekode/kunai
kunai --setup

Anime streams and curl-impersonateCopy Anchor Link

The anime providers sit behind Cloudflare. Kunai tries its own HTTP client first and falls back to curl when Cloudflare refuses it. At Miruro's API that is every time, and at AniDB's, often. A provider relay, if you run one, answers on Kunai's behalf and needs no curl. Cloudflare scores the TLS handshake, not just the User-Agent, so a plain curl is sometimes refused too even though the site is up. Either way anime search can come back with no results rather than an error, because the refusal arrives as an ordinary-looking web page; with Miruro, Kunai then falls back to searching AniList, so episodes are more likely to be the part that fails.

Most people never see this; a normal home connection is usually let through. It shows up on VPNs, corporate networks, cloud shells, and CI runners.

Run kunai doctor to see which of the three states you are in:

To move from plain to ok, install curl-impersonate:

# macOS
brew install lexiforest/tap/curl-impersonate

# Arch
sudo pacman -S curl-impersonate

There is no Debian, Fedora, or Windows package. Download a prebuilt build from curl-impersonate releases (x86_64-macos, arm64-macos, x86_64-win32, arm64-win32, and the Linux gnu/musl builds are all published) and put its curl_<browser><version> wrappers on your PATH. Kunai picks the newest desktop wrapper automatically; you do not configure which one.

On Windows those wrappers are .bat files around curl-impersonate.exe, which is what the archive ships and what Kunai looks for. Extract the whole folder and add it to PATH rather than copying the .exe out on its own; the .exe alone is not a wrapper and doctor will keep reporting plain.

This is optional. Without it Kunai still runs and still falls back to plain curl; you may just get empty anime searches on a restricted network.

Platform guardrailsCopy Anchor Link

• If an opener is missing, Kunai keeps running and leaves you in the current shell context.
• Provider and Discord live smokes are manual release checks, not background activity triggered by normal use.
• Episode numbers are 1-based in the UI; providers adapt internally.
• Discord Rich Presence uses local Unix-socket IPC on Linux/macOS (and WSL) and a named pipe on Windows-native.
• Windows-native and WSL installs are separate worlds: separate PATH, separate mpv, separate config/data.