Install and Update
Install Kunai on Linux, macOS, or Windows via the native binary or npm, then keep it current, with upgrade, rollback, and uninstall behaviour explained.
Kunai supports zero-prerequisite compiled binaries (default), global package installs, installer scripts, and source checkouts. Packaged binaries embed the Bun runtime, so you do not need Bun installed to run them. The npm channel is a Node launcher that spawns a platform binary (no Bun). bun install -g and source checkouts still need Bun.
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.Install paths
Default: downloads a verified release binary into a versioned store and links ~/.local/bin/kunai:
curl -fsSL https://kunai.kitsunekode.in/install.sh | bashThe installer downloads the platform .tar.gz, verifies it with
SHA256SUMS.archives, accepts exactly one expected regular-file member, and
verifies the extracted binary again with SHA256SUMS. It needs the standard
gzip and tar tools. Releases from before archive publication use the legacy
raw binary only when the archive or archive-checksum endpoint returns HTTP 404
or 410; integrity and network failures do not downgrade verification.
Or from an existing Kunai binary:
kunai install
kunai install --force 1.2.3On-disk layout (binary channel):
~/.local/share/kunai/versions/X.Y.Z/kunai # versioned binary
~/.local/bin/kunai # launcher symlink
~/.config/kunai/install.json # channel manifestDry run first when you want to inspect actions without creating directories or downloading:
curl -fsSL https://kunai.kitsunekode.in/install.sh | bash -s -- --dry-runIf a release asset is missing or empty, the installer prints recovery options (--method npm, --method bun, --method source, or pin --version X.Y.Z).
If ~/.local/bin is not already on PATH, the installer prints the current-shell
export plus the correct persistent command for bash, zsh, fish, or a generic
profile. It reports the actual PATH winner but does not rewrite shell startup
files automatically.
Supported binary targets: linux-x64, linux-arm64, linux-x64-musl, linux-arm64-musl, darwin-x64, darwin-arm64.
PATH
The installer puts kunai on your PATH for you. A script cannot change the
shell that launched it, so it writes your shell startup file instead, the same
thing rustup, bun, and Homebrew do, and prints one source line if you want
the current terminal to pick it up without reopening.
| Shell | File written |
|---|---|
| zsh | ~/.zshrc |
| bash | ~/.bashrc, plus one login file (~/.bash_profile, else ~/.bash_login, else ~/.profile) |
| fish | ~/.config/fish/conf.d/kunai.fish |
| anything else | ~/.profile |
| Windows | the persistent User Path environment variable |
bash gets two files because ~/.bashrc is read by interactive non-login shells
and a login shell reads only the login file; writing exactly one of the login
files keeps the line from being applied twice.
The block is delimited and written once, so re-running the installer will not stack duplicates:
# >>> kunai installer >>>
# <<< kunai installer <<<To opt out (managed environments, images, or a dotfile setup that owns
PATH itself): use --skip-path-update. The installer then prints the directory
to add and changes nothing.
Installer flags
install.sh uses POSIX flags; install.ps1 takes the same switches in
PowerShell form. Either can be set by environment variable instead, which is
what a Dockerfile or CI step usually wants.
install.sh | install.ps1 | Environment | Effect |
|---|---|---|---|
--method X | -Method X | KUNAI_INSTALL_METHOD | binary (default), npm, bun, or source. |
--version X.Y.Z | -Version X.Y.Z | KUNAI_INSTALL_VERSION | Pin a release instead of latest. |
--yes | -Yes | KUNAI_INSTALL_YES=1 | Accept Kunai's own optional prompts. It does not install system packages; see below. |
--dry-run | -DryRun | KUNAI_INSTALL_DRY_RUN=1 | Print the plan; change nothing. |
--skip-deps | -SkipDeps | KUNAI_SKIP_DEPS=1 | Skip optional dependencies (mpv via your package manager; on Windows also the portable yt-dlp and curl-impersonate helpers). |
--skip-path-update | -SkipPathUpdate | KUNAI_SKIP_PATH_UPDATE=1 | Leave PATH alone; see PATH. |
Both installers refuse to run as root / elevated by default: a sudo or
Administrator install lands Kunai in the wrong profile and the user never gets
kunai on PATH. Run as the account that will use Kunai, or opt in with
KUNAI_INSTALL_ALLOW_ROOT=1 (install.sh) / KUNAI_INSTALL_ALLOW_ELEVATED=1
(install.ps1) for a container or system install.
Without a terminal (curl … | bash in CI, a container, or a sandbox), optional
prompts are skipped, not accepted, and the installer says which step it
skipped. Before 0.3.0 a missing terminal defaulted to yes and could run
sudo apt-get/pacman/dnf install unattended.
Optional dependencies
Kunai needs mpv to play anything, and yt-dlp for YouTube. Package-manager
installs are never run for you. The installer checks whether they are already
present, and if they are not it prints the exact command for your package
manager:
! mpv is not installed — Kunai needs it to play anything.
This will run:
sudo pacman -S --needed mpv yt-dlp
Run it now? [y/N]Three rules hold for every package-manager prompt:
- The command is always shown, before it is offered and again if you decline, so nothing is hidden either way.
- The prompt defaults to no. Pressing Enter never escalates.
--yesdoes not answer this one. It is consent to install Kunai, not consent to become root or to accept a third party's licence agreements. A run with no terminal prints the command instead of running it.
Saying yes runs the command as shown, without --noconfirm, -y, or
--accept-package-agreements, so your package manager still confirms too.
On Windows, the native installer also drops portable yt-dlp and, on
x64, curl-impersonate into Kunai's own data directory
(%LOCALAPPDATA%\kunai\deps\) and puts those folders on your User PATH. These
are GitHub release binaries, verified by checksum (not winget packages), so a
one-line irm … | iex actually leaves YouTube and anime search working:
Kunai records the verified digests beside helpers it manages. A later install rechecks those bytes and repairs missing, partial, or modified helper files instead of trusting a matching filename.
yt-dlp: YouTube playback and downloads. The winget queryyt-dlpmatches bothyt-dlp.yt-dlpand a Microsoft Store listing, so the installer never runs that command; it fetchesyt-dlp.exe(oryt-dlp_arm64.exe) instead. The copy-pasteable fallback iswinget install --id yt-dlp.yt-dlp -e.curl-impersonate: Cloudflare TLS bypass for anime search (x64). There is no winget/scoop/choco package; the installer uses the same Windows archive CI pins. Windows ARM64 has no upstream build, so that host is pointed at the releases page.
The Windows curl prompt is still offered alongside these. curl-impersonate
clears Cloudflare for anime search; it does not give you an HTTP/2 curl.exe,
which is a different binary that other playback paths spawn by name. The
installer says so rather than skipping the prompt.
--skip-deps skips the portable helpers and the package-manager prompt,
including Windows curl.
Recognised managers for mpv (and for yt-dlp on Linux/macOS): pacman,
apt, dnf, zypper, apk on Linux; brew and port on macOS; winget,
scoop and choco on Windows. Anything else gets a link to
mpv's install guide.
Unsigned binaries (beta)
Release binaries are not code-signed or notarized today. That is intentional for beta:
- Windows: SmartScreen may warn on first run. After download,
install.ps1runsUnblock-Fileon the staged binary. You can also runUnblock-Filemanually onkunai.exe, or right-click → Properties → Unblock. - macOS (Apple Silicon): release binaries are cross-compiled on Linux, so they arrive unsigned, and arm64 macOS refuses to execute an unsigned Mach-O outright. The shell reports only
killed: 9: no Gatekeeper dialog, andxattrdoes not help, because quarantine is not what failed.install.shnow ad-hoc signs the binary on your Mac (codesign --force --sign -); ifcodesignis unavailable it prints the exact command to run. - macOS (Intel, or downloads outside the installer): Gatekeeper quarantine can still block a manually downloaded binary. Clear it with
xattr -dr com.apple.quarantine ~/.local/bin/kunai(or your install path). - Linux: No signing step. Archives are covered by
SHA256SUMS.archives; the extracted executable is independently covered bySHA256SUMS.
Production code signing and notarization are a post-beta goal, not a beta blocker.
Lifecycle (CLI only)
After install, all lifecycle commands run through the binary. kunai upgrade is the primary update path for every channel:
kunai install # binary install/reinstall (default)
kunai upgrade # primary channel-aware self-update
kunai upgrade --check # report only (+ install diagnostics)
kunai rollback # previous verified local version
kunai rollback --list # list local verified candidates
kunai rollback --to <ver> # explicit verified version
kunai doctor # PATH / ownership health
kunai doctor --json # same report as JSON
kunai uninstall # ownership-aware removal
kunai uninstall --purge # also delete config, data, cache, and default downloads--purge deletes downloaded videos in the default download directory:
Linux ~/.local/share/kunai/downloads (or $XDG_DATA_HOME/kunai/downloads),
macOS ~/Library/Application Support/kunai/downloads, and Windows
%LOCALAPPDATA%\kunai\downloads. Custom/external download directories outside
Kunai's config, data, and cache directories are preserved.
Install scripts (install.sh, install.ps1) only install. They do not upgrade or uninstall; lifecycle logic stays inside the binary.
kunai --version shows the active install channel when install.json is present.
Update checks
Kunai runs a cached, non-blocking background update check at startup.
Release-metadata requests stop after 15 seconds, so an unavailable GitHub or npm
endpoint cannot leave startup checks or kunai upgrade waiting indefinitely.
- Binary installs: when
autoApplyBinaryUpdatesis enabled (default), Kunai downloads and stages the new version underversions/automatically. Restart Kunai to run the new binary. Toggle this from/update. - npm/bun/source: notify-only; run
kunai upgradeor your package manager manually. - Turning it off: set
updateChecksEnabledtofalseinconfig.json(defaulttrue) and Kunai stops checking entirely: no background request, and no update notice.
Manual check from the shell:
/updateThe update panel shows install-method-aware guidance:
| Install method | Typical update path |
|---|---|
| Binary (default) | kunai upgrade or background auto-apply (restart to pick up) |
| Source checkout | Pull the repository, refresh dependencies/build as needed |
| Bun global | bun update --global @kitsunekode/kunai or kunai upgrade |
| npm global | npm install -g @kitsunekode/kunai or kunai upgrade |
You can snooze automatic checks for seven days or disable them from the update panel. Manual /update always remains available.
Platform support matrix (0.3.0)
| Target | Status |
|---|---|
linux-x64, linux-arm64 (glibc) | Supported |
linux-x64-musl, linux-arm64-musl (Alpine) | Supported |
darwin-x64, darwin-arm64 | Beta |
windows-x64 | Beta |
windows-arm64 | Experimental |
| WSL | Linux binary + Linux mpv/PATH/data, not Windows-native |
| FreeBSD / other BSD | Unsupported binary; npm/bun/source only |
| Code signing / notarization | Not in beta scope; see Unsigned binaries above |
Alpine / musl quick start
apk add mpv yt-dlp ffmpeg
curl -fsSL https://kunai.kitsunekode.in/install.sh | bash
kunai --version
kunai --setupWindows-native vs WSL
| Concern | Windows-native | WSL |
|---|---|---|
| Installer | install.ps1 | Linux install.sh inside the distro |
| Binary | kunai.exe under %LOCALAPPDATA%\kunai\bin | ~/.local/bin/kunai (Linux) |
| Player | Windows mpv.exe on User PATH | Linux mpv on WSL PATH |
| Config / data | %APPDATA%\kunai, %LOCALAPPDATA%\kunai | ~/.config/kunai, ~/.local/share/kunai |
| Protocol handler | Not registered; use kunai --open | Linux-only registration available |
Do not point a Windows-native Kunai at WSL mpv, or a WSL Kunai at Windows PATH entries.
When install, PATH, ownership, checksum, or rollback fails, see Installer troubleshooting. Isolated Docker installer smokes are contributor-only; see Contribute.
Override the download mirror for air-gapped or future CDN hosting:
KUNAI_DL_BASE=https://github.com/KitsuneKode/kunai/releases ./install.shRelease notes and support
Published versions live on GitHub Releases. After updating, run /update inside Kunai to confirm the active version and install method.
For support after an update:
- Run
/report-issuefrom Kunai for a guided bundle path. - For verbose traces, launch with
--debug-session, reproduce, then/export-diagnostics.
Contributor release steps: Docs maintenance.
More flag detail: CLI Reference.
Last updated on
Getting Started
Install Kunai, put it on your PATH, install mpv, run setup, and complete a first playback session end to end, with the exact commands for your platform.
Platforms
Platform-specific notes for Kunai on Linux, macOS, and Windows: install, playback, poster support, protocol handlers, and the troubleshooting each one needs.