Install And Update
Install Kunai across platforms and keep source, global, and packaged installs current.
Kunai supports zero-prerequisite compiled binaries (default), global package installs, installer scripts, and source checkouts. Packaged binaries embed the Bun runtime — you do not need Bun installed to run them. npm/bun/source channels still require Bun for the JS bundle runtime.
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 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.Install paths
Default — downloads a verified release binary into a versioned store and links ~/.local/bin/kunai:
curl -fsSL https://raw.githubusercontent.com/KitsuneKode/kunai/main/install.sh | bashOr 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://raw.githubusercontent.com/KitsuneKode/kunai/main/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.
irm https://raw.githubusercontent.com/KitsuneKode/kunai/main/install.ps1 | iexInstalls to %LOCALAPPDATA%\kunai\bin\kunai.exe, prepends that directory to your User PATH so the native binary wins over an older npm/Bun shim, and records the install channel in %APPDATA%\kunai\install.json.
Open a new terminal after installation if kunai is not visible yet. The
installer also prints the resolved PATH winner so an older npm/Bun shim cannot
silently shadow the native binary.
Supported binary targets: windows-x64, windows-arm64.
bun install -g @kitsunekode/kunai
kunai --setupRequires Bun on your PATH (the published entry is #!/usr/bin/env bun):
npm install -g @kitsunekode/kunai
kunai --setupGlobal npm installs write install.json automatically via bundled postinstall so ownership-aware kunai upgrade / kunai uninstall route correctly. Diagnose PATH shadows with kunai doctor.
Contributor-oriented — not the preferred end-user path:
git clone https://github.com/KitsuneKode/kunai.git
cd kunai
bun install
bun run link:global
kunaiUnsigned 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: Gatekeeper may block unsigned binaries. Remove the quarantine attribute if needed:
xattr -dr com.apple.quarantine ~/.local/bin/kunai(or your install path). - Linux: No signing step; verify downloads against the
SHA256SUMSfile published on each GitHub Release.
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/history/cacheInstall 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.
- 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.
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://raw.githubusercontent.com/KitsuneKode/kunai/main/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.
Override the download mirror for air-gapped or future CDN hosting:
KUNAI_DL_BASE=https://github.com/KitsuneKode/kunai/releases ./install.shDocker smoke (isolated, no host install)
To verify install/upgrade/uninstall end-to-end without touching ~/.local/bin or ~/.config/kunai:
bun run test:installer:docker
# or: bash apps/cli/test/docker/native-installer/run-local.shThis builds linux-x64 + musl binaries, serves a mock release from a temp directory, and runs the full flow inside Debian (glibc) and Alpine (musl) containers with HOME=/tmp/kunai-home only.
Release 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