# Doctor (/docs/v0.4/cli/doctor)



```bash
koshi doctor
koshi doctor --format json
```

```text
check               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 [#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 [#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 [#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 [#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 [#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](/docs/v0.4/using/other-users#where-the-sockets-live).