Doctor
koshi doctor rates this machine's installation — config, shell, terminal, directories, router, session directory, and remote access — one row per check.
koshi doctor
koshi doctor --format jsoncheck verdict reason help
config ok 3 config files validated -
shell ok a new pane runs /bin/zsh -
terminal warn TERM is not set set TERM before running koshi, for example TERM=xterm-256color
runtime directory ok /tmp/koshi-1000 is ready; koshi names it after your user id -
log directory ok /home/you/.local/state/koshi/logs is writable and logging is off -
plugins directory ok /home/you/.config/koshi/plugins is readable -
router ok no koshi is running -
session directory ok sessions are advertised in /tmp/koshi-1000 (mode 700), which only you may reach -
remote access ok koshi.kdl names no remote listen address, and this machine holds 0 standing grants -
remote connections ok no koshi is running, so nothing from another machine is connected -koshi doctor runs on the machine it is about. koshi doctor --remote is
refused.
Verdicts
| Cell | Meaning |
|---|---|
ok | The check found what it looks for |
warn | The check found something that still works and is worth reading |
fail | The check found something koshi cannot work through |
The whole answer prints either way. A run holding a fail row exits 1; a run
of only ok and warn rows exits 0.
The checks, in order
| Check | What it reads |
|---|---|
config | Every config file in the config directory, validated the way koshi config check validates it |
shell | koshi.kdl's terminal.default-shell, else SHELL on Linux and macOS and COMSPEC on Windows, and whether the program it names exists |
terminal | TERM and COLORTERM |
runtime directory | Which directory it is, that it can be read, that it is private, and which rule produced its path |
log directory | That a file can be written there, and whether koshi.kdl turns logging on |
plugins directory | That it exists and can be read |
router | Whether a router answers on its control socket |
session directory | Where sessions are advertised, and who may reach that directory |
remote access | koshi.kdl's remote listen address, and how many access grants still stand |
remote connections | How many open connections the running router holds from another machine |
What each row does and does not do
koshi doctor starts no koshi and creates no directory. The plugins directory row reads the directory and opens no plugin. The log directory row
writes one empty file in the log directory and removes it again — that is how
it reports whether the directory can be written.
The session directory and remote connections rows report facts and rate
nothing. The remote access row rates one thing: it reads warn when the
grants could not be read.
router is the only row that rates the running router. A router whose build
has no such question is warn; a router that is listening and does not answer
is fail. Either way remote connections reads the running router did not answer, so this is not known.
A router that answers but whose build reports no count reads the running router reports no count, so this is not known. A count of 0 prints only when
the router sent one.
Long reasons
A row whose reason is shortened to fit the table carries the whole text in a
detail field, which --format json prints and the table leaves out. Every
other row has "detail": null.
The runtime directory
koshi keeps its router socket and its session sockets in one directory per user.
| Platform | Directory |
|---|---|
| Linux, macOS | /tmp/koshi-<your user id> |
| Windows | run under your application data directory |
KOSHI_RUNTIME_DIR names the directory instead, and koshi reads it only when
it holds an absolute path. A relative value is ignored. Two koshi processes
holding different values use different directories and do not find each other.
koshi doctor prints the directory in use and the rule that produced it. See
Sharing with other users.