Customization

Configure Kunai through config.json, provider overrides, mpv forwarding, shell density, and Discord presence.

Kunai stores preferences locally. Most settings are editable from /settings or /setup inside the shell. Advanced users can edit JSON directly.

Config locations

File	Purpose
`~/.config/kunai/config.json`	User preferences, provider priority, language profiles, presence, downloads
`~/.config/kunai/providers.json`	Optional per-provider base domain overrides
`~/.config/kunai/install.json`	Install channel metadata (binary / npm / bun)

config.json

The main config file is created on first run or after kunai --setup. Kunai merges saved values with defaults on load — you do not need every key present.

Mode and providers

Key	What it controls
`defaultMode`	`series` or `anime` startup mode
`provider`	Default movie/series provider for new sessions
`animeProvider`	Default anime provider
`providerPriority`	Fallback order for movie/series providers (empty = registry default)
`animeProviderPriority`	Fallback order for anime providers
`titleProviderPreferences`	Per-title provider override chosen explicitly by the user

Unknown provider ids in priority arrays are ignored. Providers not listed remain available after configured entries.

YouTube metadata and cookies

{
  "youtubeMetadata": {
    "cookiesFromBrowser": "firefox",
    "cookiesFile": "/absolute/path/to/cookies.txt"
  }
}

cookiesFromBrowser — optional browser profile name for yt-dlp (no default).
cookiesFile — optional absolute path to a cookie file (no default).
Never paste cookie contents into issues or chat. Review redacted /export-diagnostics bundles before sharing.
Kunai does not bypass DRM or YouTube access controls; cookies only help yt-dlp with content your account can already play.

See Providers → YouTube.

Provider relay

providerRelay is optional. Leave baseUrl empty for direct provider fetches only. Set it when you run your own relay for provider metadata APIs that are geo-blocked from your network.

{
  "providerRelay": {
    "baseUrl": "https://your-relay.example",
    "token": "",
    "fallbackToDirect": true,
    "providers": {
      "allanime": { "enabled": true }
    }
  }
}

KUNAI_RELAY_BASE_URL and KUNAI_RELAY_TOKEN override local config for smoke tests and temporary sessions. The relay is metadata-only by default; Kunai does not proxy video unless a provider explicitly supports and enables video fallback.

Language and media profiles

Kunai uses separate profiles for anime, series, and movies:

{
  "animeLanguageProfile": { "audio": "ja", "subtitle": "en", "quality": "1080" },
  "seriesLanguageProfile": { "audio": "en", "subtitle": "en" },
  "movieLanguageProfile": { "audio": "en", "subtitle": "en" }
}

animeTitlePreference — display English, romaji, native, or provider-native titles.
favoriteSources — pin preferred source/server names to the top of pickers.

See Media selection for how profiles flow into resolution and mpv.

Playback and recovery

Key	What it controls
`autoNext`	Autoplay next episode when available
`autoplayRecommendations`	YouTube-style continue into top recommendation when caught up
`skipIntro`, `skipRecap`, `skipPreview`, `skipCredits`	Auto-skip segments when timing metadata exists
`recoveryMode`	`guided`, `fallback-first`, or `manual`
`resumeStartChoicePrompt`	Resume vs start-over overlay when resuming mid-episode
`quitNearEndBehavior`	What happens when you quit mpv near the natural end

Shell density and chrome

Key / flag	Effect
`zenMode` / `--zen`	Single-column, minimal chrome — all features still key-reachable
`minimalMode` / `--minimal`	Collapse companion pane and dim header status
`footerHints`	`detailed` or `minimal` footer guidance
`discoverShowOnStartup`	Faint discover hint in browse footer when history exists
`powerSaverMode`	Suppress background network and speculative work

Kunai ships with the Sakura design system baked into the terminal UI. There is no separate theme picker today — density modes (zen, minimal) are how you reduce visual chrome.

Downloads and offline

Key	What it controls
`downloadsEnabled`	Gate for download features (off until opted in)
`downloadPath`	Custom download directory (empty = app data default)
`maxConcurrentDownloads`	Parallel download jobs (clamped 1–5)
`offlineFreeSpaceReserveBytes`	Reserved disk space before accepting new downloads
`defaultDownloadQuality`	Shared quality floor for new download jobs
`offlineMode`	Persistent local-only shell posture (separate from `--offline` launch)
`autoCleanupWatched`	Surface watched downloads as cleanup candidates

See Downloads and offline.

Sync integrations (opt-in)

{
  "sync": {
    "anilist": { "enabled": false, "trackWatched": false, "syncList": false },
    "tmdb": { "enabled": false, "trackWatched": false, "syncList": false }
  }
}

Tokens are stored separately. Sync never runs unless explicitly enabled.

providers.json overrides

Advanced users can override provider base domains without editing code:

{
  "videasy": "https://mirror.example",
  "vidlink": "https://alt.example"
}

File path: ~/.config/kunai/providers.json
Keys match provider ids from the production registry.
vidking remains accepted as a legacy alias for videasy.
Overrides affect URL construction only — they do not add new providers.

Overrides do not fix broken providers

Domain overrides help when a provider moves mirrors. They do not bypass DRM, add authentication, or guarantee stream availability.

mpv flags and bridge options

Kunai always launches mpv for playback. You can forward diagnostic flags for a single run:

Flag	Effect
`--mpv-debug`	Verbose mpv logging
`--mpv-clean`	Minimal mpv config for isolation testing
`--no-user-mpv-config`	Ignore user mpv.conf for this run
`--mpv-log-file <path>`	Write mpv log to a specific file

These are process flags — see CLI reference.

Persistent mpv bridge settings

Config keys tune the Kunai Lua bridge script:

Key	Purpose
`mpvKunaiScriptPath`	Custom path to `kunai-bridge.lua` (empty = auto-resolve)
`mpvKunaiScriptOpts`	`--script-opts` entries for the bridge (e.g. `margin_bottom`, `chip_width`)
`mpvInProcessStreamReconnect`	Reload same URL after network-read-dead stalls
`mpvInProcessStreamReconnectMaxAttempts`	Max reload attempts per playback cycle

Example mpvKunaiScriptOpts:

{
  "mpvKunaiScriptOpts": {
    "margin_bottom": "130",
    "prompt_seconds": "8"
  }
}

Kunai still passes provider-required headers (referrer, user-agent) and subtitle attachments automatically. Do not expect arbitrary mpv CLI passthrough from config today — use the flags above for debugging.

Discord presence setup

Discord Rich Presence is off by default and local-only.

Open presence settings

/presence

Or use /settings and navigate to Presence.

Choose provider and privacy

Set Presence to discord.
Set Presence privacy to full (title/episode detail) or private (generic activity).

Provide a Discord application client id

Enter a numeric Discord application client id in Settings, or set:

export KUNAI_DISCORD_CLIENT_ID="your_app_id"

Create an application at Discord Developer Portal if you need a new id.

Connect and verify

Use Connect Discord now in Settings. Kunai connects through Discord's local IPC — Unix socket on Linux/macOS, named pipe on Windows — no cloud relay.

While playing, Kunai updates episode cards and progress timestamps. Paused playback shows static text; activity clears after a configurable idle delay.

Diagnostics record presence connect/clear failures. Check /diagnostics if Discord shows unavailable or error.

More: Diagnostics and reporting.

Editing config safely

Use /settings or /setup for guided changes. Settings persist immediately to config.json.

Quit Kunai (or edit while idle — avoid editing mid-playback).
Edit ~/.config/kunai/config.json with valid JSON.
Restart Kunai. Invalid JSON falls back to defaults with a stderr warning.

Reset without uninstall

Delete config.json to reset preferences. Use kunai uninstall --purge only when you want config, history, and cache removed together.

Providers — fallback chains and priority
Media selection — language profiles in practice
Troubleshooting — when config changes do not fix playback

Kunai stores preferences locally. Most settings are editable from /settings or /setup inside the shell. Advanced users can edit JSON directly.

Config locations

File	Purpose
`~/.config/kunai/config.json`	User preferences, provider priority, language profiles, presence, downloads
`~/.config/kunai/providers.json`	Optional per-provider base domain overrides
`~/.config/kunai/install.json`	Install channel metadata (binary / npm / bun)

config.json

The main config file is created on first run or after kunai --setup. Kunai merges saved values with defaults on load — you do not need every key present.

Mode and providers

Key	What it controls
`defaultMode`	`series` or `anime` startup mode
`provider`	Default movie/series provider for new sessions
`animeProvider`	Default anime provider
`providerPriority`	Fallback order for movie/series providers (empty = registry default)
`animeProviderPriority`	Fallback order for anime providers
`titleProviderPreferences`	Per-title provider override chosen explicitly by the user

Unknown provider ids in priority arrays are ignored. Providers not listed remain available after configured entries.

YouTube metadata and cookies

{
  "youtubeMetadata": {
    "cookiesFromBrowser": "firefox",
    "cookiesFile": "/absolute/path/to/cookies.txt"
  }
}

cookiesFromBrowser — optional browser profile name for yt-dlp (no default).
cookiesFile — optional absolute path to a cookie file (no default).
Never paste cookie contents into issues or chat. Review redacted /export-diagnostics bundles before sharing.
Kunai does not bypass DRM or YouTube access controls; cookies only help yt-dlp with content your account can already play.

See Providers → YouTube.

Provider relay

providerRelay is optional. Leave baseUrl empty for direct provider fetches only. Set it when you run your own relay for provider metadata APIs that are geo-blocked from your network.

{
  "providerRelay": {
    "baseUrl": "https://your-relay.example",
    "token": "",
    "fallbackToDirect": true,
    "providers": {
      "allanime": { "enabled": true }
    }
  }
}

Language and media profiles

Kunai uses separate profiles for anime, series, and movies:

{
  "animeLanguageProfile": { "audio": "ja", "subtitle": "en", "quality": "1080" },
  "seriesLanguageProfile": { "audio": "en", "subtitle": "en" },
  "movieLanguageProfile": { "audio": "en", "subtitle": "en" }
}

animeTitlePreference — display English, romaji, native, or provider-native titles.
favoriteSources — pin preferred source/server names to the top of pickers.

See Media selection for how profiles flow into resolution and mpv.

Playback and recovery

Key	What it controls
`autoNext`	Autoplay next episode when available
`autoplayRecommendations`	YouTube-style continue into top recommendation when caught up
`skipIntro`, `skipRecap`, `skipPreview`, `skipCredits`	Auto-skip segments when timing metadata exists
`recoveryMode`	`guided`, `fallback-first`, or `manual`
`resumeStartChoicePrompt`	Resume vs start-over overlay when resuming mid-episode
`quitNearEndBehavior`	What happens when you quit mpv near the natural end

Shell density and chrome

Key / flag	Effect
`zenMode` / `--zen`	Single-column, minimal chrome — all features still key-reachable
`minimalMode` / `--minimal`	Collapse companion pane and dim header status
`footerHints`	`detailed` or `minimal` footer guidance
`discoverShowOnStartup`	Faint discover hint in browse footer when history exists
`powerSaverMode`	Suppress background network and speculative work

Kunai ships with the Sakura design system baked into the terminal UI. There is no separate theme picker today — density modes (zen, minimal) are how you reduce visual chrome.

Downloads and offline

Key	What it controls
`downloadsEnabled`	Gate for download features (off until opted in)
`downloadPath`	Custom download directory (empty = app data default)
`maxConcurrentDownloads`	Parallel download jobs (clamped 1–5)
`offlineFreeSpaceReserveBytes`	Reserved disk space before accepting new downloads
`defaultDownloadQuality`	Shared quality floor for new download jobs
`offlineMode`	Persistent local-only shell posture (separate from `--offline` launch)
`autoCleanupWatched`	Surface watched downloads as cleanup candidates

See Downloads and offline.

Sync integrations (opt-in)

{
  "sync": {
    "anilist": { "enabled": false, "trackWatched": false, "syncList": false },
    "tmdb": { "enabled": false, "trackWatched": false, "syncList": false }
  }
}

Tokens are stored separately. Sync never runs unless explicitly enabled.

providers.json overrides

Advanced users can override provider base domains without editing code:

{
  "videasy": "https://mirror.example",
  "vidlink": "https://alt.example"
}

File path: ~/.config/kunai/providers.json
Keys match provider ids from the production registry.
vidking remains accepted as a legacy alias for videasy.
Overrides affect URL construction only — they do not add new providers.

Overrides do not fix broken providers

Domain overrides help when a provider moves mirrors. They do not bypass DRM, add authentication, or guarantee stream availability.

mpv flags and bridge options

Kunai always launches mpv for playback. You can forward diagnostic flags for a single run:

Flag	Effect
`--mpv-debug`	Verbose mpv logging
`--mpv-clean`	Minimal mpv config for isolation testing
`--no-user-mpv-config`	Ignore user mpv.conf for this run
`--mpv-log-file <path>`	Write mpv log to a specific file

These are process flags — see CLI reference.

Persistent mpv bridge settings

Config keys tune the Kunai Lua bridge script:

Key	Purpose
`mpvKunaiScriptPath`	Custom path to `kunai-bridge.lua` (empty = auto-resolve)
`mpvKunaiScriptOpts`	`--script-opts` entries for the bridge (e.g. `margin_bottom`, `chip_width`)
`mpvInProcessStreamReconnect`	Reload same URL after network-read-dead stalls
`mpvInProcessStreamReconnectMaxAttempts`	Max reload attempts per playback cycle

Example mpvKunaiScriptOpts:

{
  "mpvKunaiScriptOpts": {
    "margin_bottom": "130",
    "prompt_seconds": "8"
  }
}

Discord presence setup

Discord Rich Presence is off by default and local-only.

Open presence settings

/presence

Or use /settings and navigate to Presence.

Choose provider and privacy

Set Presence to discord.
Set Presence privacy to full (title/episode detail) or private (generic activity).

Provide a Discord application client id

Enter a numeric Discord application client id in Settings, or set:

export KUNAI_DISCORD_CLIENT_ID="your_app_id"

Create an application at Discord Developer Portal if you need a new id.

Connect and verify

Use Connect Discord now in Settings. Kunai connects through Discord's local IPC — Unix socket on Linux/macOS, named pipe on Windows — no cloud relay.

While playing, Kunai updates episode cards and progress timestamps. Paused playback shows static text; activity clears after a configurable idle delay.

Diagnostics record presence connect/clear failures. Check /diagnostics if Discord shows unavailable or error.

More: Diagnostics and reporting.

Editing config safely

Use /settings or /setup for guided changes. Settings persist immediately to config.json.

Quit Kunai (or edit while idle — avoid editing mid-playback).
Edit ~/.config/kunai/config.json with valid JSON.
Restart Kunai. Invalid JSON falls back to defaults with a stderr warning.

Reset without uninstall

Delete config.json to reset preferences. Use kunai uninstall --purge only when you want config, history, and cache removed together.

Providers — fallback chains and priority
Media selection — language profiles in practice
Troubleshooting — when config changes do not fix playback

Customization

config.json

Mode and providers

YouTube metadata and cookies

Provider relay

Language and media profiles

Playback and recovery

Shell density and chrome

Downloads and offline

Sync integrations (opt-in)

providers.json overrides

mpv flags and bridge options

Persistent mpv bridge settings

Discord presence setup

Open presence settings

Choose provider and privacy

Provide a Discord application client id

Connect and verify

Editing config safely

On this page

Customization

config.json

Mode and providers

YouTube metadata and cookies

Provider relay

Language and media profiles

Playback and recovery

Shell density and chrome

Downloads and offline

Sync integrations (opt-in)

providers.json overrides

mpv flags and bridge options

Persistent mpv bridge settings

Discord presence setup

Open presence settings

Choose provider and privacy

Provide a Discord application client id

Connect and verify

Editing config safely

On this page