CLI
kōan is a single binary with subcommands. Running koan with no subcommand launches the TUI player.
koan play
Play audio files or open the TUI player. Running koan with no subcommand is equivalent to koan play.
koan # TUI
koan play # same as above
koan play ~/Music/album/ # play a directory (recursive)
koan play ~/Music/*.flac # play specific files
koan play --album 5 # play album by ID (use tab completion)
koan play --artist 3 # play artist by ID
koan play --library # TUI in library browse mode
koan play --clear # clear persisted queue
koan --api # TUI + GraphQL/Subsonic API on 127.0.0.1:4000Server flags
These are root-level flags (not under play). The TUI serves the API only when asked: --api, any of --port, --bind, --subsonic or --playground, or [graphql] enabled = true. A server with no accounts lets whoever opens /setup first become its admin, so one started without being asked for would hand that to any local process. --no-api overrides the config.
koan --headless # serve on 127.0.0.1:4000, no TUI (needs server.url)
koan --headless --playground # with GraphiQL at /graphql
koan --headless --subsonic 4040 # Subsonic also on a port of its own
koan --port 8080 # TUI + API on a custom port
koan --bind 0.0.0.0 # listen on all interfaces (auth enabled by default)
koan -d # background daemon
koan -d --subsonic 4040 # daemon with Subsonic
koan --no-api # TUI without the API, whatever the config says--headless and -d refuse to start without server.url (KOAN_SERVER__URL), the address clients reach the server at; see Configuration.
Remote TUI
koan play --server http://host:4000 # remote control for a koan serverThe server plays the audio. To listen on this machine, sign in to the server as a remote library (koan remote login) and play through the local engine. --jukebox is still accepted and changes nothing.
MCP server
koan mcp # MCP server on stdio (Claude Desktop)See MCP Integration for setup instructions.
koan config init
Create the config directory with a commented template.
koan config initWrites config.toml with every default commented out. Re-running adds new defaults without touching your changes.
See Configuration for details on what gets created.
koan scan
Scan configured library folders and index metadata.
koan scan # scan the configured library folders
koan scan ~/Music/new # scan one folder
koan scan --force # read every file's tags againOnly files whose modification time or size changed are re-read; --force re-reads everything. See Getting started for --force-remove.
koan search
Full-text search across your library (CLI output).
koan search "radiohead"
koan search "kind of blue"Uses SQLite FTS5 with prefix matching. Results display as a tree: artist -> album -> track.
koan library
Show library statistics.
koan librarykoan remote
Manage Subsonic/Navidrome remote servers.
koan remote login URL user # authenticate (prompts for password)
koan remote sync # sync the library, favourites and playlists
koan remote status # show remote server infoSee Remote Servers for the full guide.
koan subsonic
Manage kōan's own Subsonic-compatible REST API at /rest/*.
koan subsonic setup # generate a secret and enable the API
koan subsonic setup --username me # pick the username (default: koan)
koan subsonic status # show whether it is enabled and configured
koan subsonic disable # stop serving /rest/* and delete the secretThe secret is separate from your [remote] (Navidrome) password and is printed once. See Configuration for why.
koan config
Show the resolved configuration from all layers.
koan configPrints which config files were read, the names of any active KOAN_* environment variables, and the merged result, with secrets masked.
koan dsp
Equalisation and convolution, per output device. See Equalisation and convolution.
koan dsp [show] [DEVICE] [--json] # what a device plays: the chain in a sentence, then each stage
koan dsp set DEVICE --correction NAME|none --tuning EQ,EQ…|none # the whole chain in one go; repeating it changes nothing; an empty value is none
koan dsp flat [DEVICE] # no correction or tuning: plays untouched
koan dsp list [--json] # every correction, EQ and preset, and where each is used
koan dsp preset save NAME [--device NAME] # a device's correction and tuning, saved together
koan dsp preset use NAME|flat [--device NAME] # set a device from a preset, or flat
koan dsp preset list [--json] # the presets, and the devices set from each
koan dsp import "Harman 780.zip" # Roon zip, .cfg, WAVs, CamillaDSP, APO, AutoEQ…
koan dsp import L48.wav R48.wav --name Room --device "Topping E30"
koan dsp import room.txt --rate 48000 # coefficients that do not say their rate
koan dsp remove NAME
koan dsp autoeq search QUERY [--limit N] [--refresh] # AutoEQ results by headphone name, numbered
koan dsp autoeq install NUMBER|NAME [--source SOURCE] [--device NAME]
koan dsp target NAME [--use TARGET | --reset] # move an AutoEQ correction to another target
koan dsp add-target FILE # a target from a CSV or squig.link export
koan dsp measure FILE... --name NAME --ear in|over|speaker --target TARGET # correct from a measurement; a speaker's two Klippel planes together, to flat
koan dsp response [DEVICE] [--correction NAME] [--tuning EQ,...|none] [--rate HZ] # what the chain plays, as CSV on AutoEQ's grid; nothing saved
koan dsp role NAME correction|tuning|mixed # mixed: a correction that already includes a tuning
koan dsp made-for NAME TARGET|unknown # the target a ready-made EQ was made for
koan dsp tuned-for NAME TARGET|unknown # the target a tuning was made against
koan dsp revert NAME # an imported EQ back as imported
koan dsp copy NAME [NEW] # a copy as it is now, used by no device
koan dsp split NAME FILE --ear in|over --target TARGET # a mixed correction into a correction and an EQ
koan dsp squig QUERY [--limit N] # measurements on squig.link sites, numbered
koan dsp squig QUERY --use-result N --target TARGET [--ear in|over] [--name NAME] # a correction from one
koan dsp eq plays NAME EQ... # one EQ built from others, played in order
koan dsp eq switch NAME EQ on|off # switch one of the EQs it plays on or offkoan dsp --help opens with worked examples:
koan dsp set "Scarlett 4i4 USB" --correction "Wharfedale EVO 4.1" --tuning Lush
koan dsp preset save "Desk" --device "Scarlett 4i4 USB"
koan dsp show "Scarlett 4i4 USB" --jsonshow --json gives device, correction, target, tuning (each name, on, made_for, matched, join and note), preset, edited, left_out (EQs that do not play), notes (why), flat and sentence. A tuning EQ's matched is true where it was made against the correction's target, false where it was made against another or that is not set, and null where there is nothing to compare; join.state is matched, converted (with from and to) or unknown, the last meaning the EQ does not say what it was made against. list --json gives each one's name, kind (correction, eq or preset), used_on, edited, members (a group's) and problem (why it would not load); preset list --json gives each preset's name, used_on and edited. A refusal says what is wrong and the valid choices ("No correction called X. Corrections: …") and exits non-zero.
The names from before still work, out of the help: use (now set --correction or preset use), clear (flat), tuning (set --tuning), stack and layer (eq plays, eq switch), and role … baked (mixed).
--device defaults to the current output: [playback] output_device, or the system default.
koan devices
List available audio output devices.
koan devicesShows device names as recognized by CoreAudio (macOS) or ALSA/cpal (Linux). Use these names for the [playback] output_device config field or the D device selector in the TUI.
koan cache
Manage the download cache for remote tracks.
koan cache status # show cache size and track count
koan cache clear # clear all cached downloads (--yes/-y to skip confirmation)
koan cache evict # run LRU eviction based on cache_limitSee Cache Management for details.
koan auth
Manage authentication -- users, tokens, keypair.
koan auth setup # generate keypair + create first admin user
koan auth create-user --username alice --role user # create a user (admin, user, readonly)
koan auth delete-user alice # delete a user
koan auth list-users # list all users
koan auth login --server http://localhost:4000 --username admin # login (stores refresh token in config.local.toml)
koan auth logout --server http://localhost:4000 # logout (revoke token)
koan auth reset-password admin # reset password (revokes all tokens for that user)
koan auth set-role alice admin # change role
koan auth api-key create --username alice --name phone # Subsonic API key, printed once
koan auth api-key list [--username alice] # keys with created / last used
koan auth api-key revoke 3 # revoke a key by id
koan auth regenerate-keys # regenerate Ed25519 keypair (invalidates all tokens)
koan auth reset # delete all keys, users, tokensWithout a terminal, or with --non-interactive, koan auth never prompts: credentials come from KOAN_USERNAME and KOAN_PASSWORD, destructive commands need --yes, and 1Password is used only with --save-to-1password.
KOAN_USERNAME=admin KOAN_PASSWORD=secret koan auth setup
KOAN_PASSWORD=secret koan auth create-user --username alice --role user
koan auth delete-user alice --yesSee Authentication for the full guide.
koan auth invite
koan auth invite alice # an invite link for the account, and the email to send it in
koan auth invite alice --reset-password # also a new password, signing the account's devices out
koan auth invite alice --server https://music.example.com # a different address from server.urlSee Invites.
koan check-db
koan check-db # can this build open the configured database?
koan check-db path/to/koan.dbRuns this build's migrations on a snapshot of the database, leaving the original untouched, and exits non-zero if they fail. Useful before upgrading a server.
koan probe
Show format and codec info for a file.
koan probe track.flacDisplays codec, sample rate, bit depth, channels, duration, and tag summary.
Shell completions
Dynamic completions that know your library -- artist/album IDs tab-complete from the database.
# zsh (add to .zshrc)
source <(COMPLETE=zsh koan)
# bash
source <(COMPLETE=bash koan)
# fish
COMPLETE=fish koan | sourceThen koan play --album <TAB> shows your actual albums with artist names.
koan completions SHELL prints static completions (subcommands and flags only) for shells or setups that cannot run the dynamic ones.