Diagnostics
TL;DR: Run
fut doctor. It safely checks configuration, terminal capabilities, runtime permissions, daemon compatibility, and icons without starting or changing anything.
fut doctor performs a bounded, read-only diagnosis of the client environment:
fut doctor
fut --json doctor
fut --socket /path/to/fut.sock doctor
It does not start or stop a daemon, create or repair directories, remove stale sockets, open a project, spawn a terminal, enter raw mode, or change terminal state.
Checks
Doctor reports:
- the resolved configuration source, file presence, parsing, and validation;
TERM, color hints, TTY attachment, and the terminal program hint;- whether the selected locale declares UTF-8;
- runtime-directory ownership and private permissions;
- socket type, ownership, and permissions;
- a bounded Fut protocol handshake when a safe socket exists;
- the active daemon extension generation, fingerprint, package count, manifest metadata, canonical roots, and configuration provenance;
- the configured icon preset and a visual glyph probe.
Released client and daemon protocol versions must match exactly. Compatible source changes keep the current release’s protocol during development. The protocol is derived from the package version’s minor component, so Fut 0.12.x uses protocol 12 and the next minor release advances it automatically. Doctor reports both versions when it can safely reach a daemon.
Configuration validation and active extension reporting are independent. If a changed package on disk is incompatible or malformed, the config check explains why that candidate is rejected while the extensions check still identifies the daemon’s last-known-good active generation. Doctor only reads manifests and the daemon catalog; it never executes extension hooks or commands.
Nerd Fonts
Terminal processes have no reliable cross-terminal API for discovering the active font. Doctor therefore reports the active font as unknown and asks for visual verification. It does not infer support from the terminal program or claim that an installed font is selected.
Enabling preset = "nerd_font" makes the icon check a warning until visually verified; it does not prevent Fut from starting.
Exit status
0: the report contains no errors; informational checks and warnings are allowed.1: one or more checks are errors, such as malformed configuration,TERM=dumb, insecure runtime state, or an incompatible endpoint.
Diagnosed errors are part of the complete report rather than a secondary command failure.
JSON
fut --json doctor writes one compact success-envelope-shaped report to stdout, even when the report’s status is error and the process exits 1:
{"version":1,"command":"doctor","result":{"status":"warning","checks":[{"id":"config","status":"ok","summary":"valid defaults; no configuration file"}]}}
Check statuses are ok, info, warning, and error. Details include
structured paths, environment hints, protocol versions, active extension
package metadata and provenance, icon glyphs, and the explicit
active_font: "unknown" limitation where applicable.