Diagnostics

TL;DR: Run fut doctor. It safely checks configuration, terminal capabilities, runtime permissions, daemon and saved-machine 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;
• whether the ssh executable identifies itself as OpenSSH;
• saved-machine catalog validity and enabled/disabled profile summaries;
• a bounded, non-interactive compatibility handshake to each enabled saved machine, with at most four probes in flight;
• the configured icon preset and a visual glyph probe.

Remote probes use BatchMode=yes and strict host-key checking. They do not prompt, accept host keys, edit SSH configuration, write the machine catalog, start or stop a daemon, or lease a terminal. A profile can therefore report an authentication, host-key, installation, timeout, or protocol error that must be repaired with ordinary OpenSSH and Fut commands outside doctor. Every probe closes and reaps its SSH process before the report completes.

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.

Related

• Configuration
• Presentation tokens