LILYLILYDOCS
HomepageLogin
Docs/CLI/doctor

lly doctor

Sanity-check your local install before you debug anything else.

lly doctor is a single command that inspects your local install and prints one line per check. It is intentionally boring. If something is wrong with your environment, doctor finds it in under a second so you do not waste time chasing a bug that is not in your code.

Run it first whenever a compile, run, or deploy starts behaving strangely. The output is stable and grep-friendly.

What it checks

Doctor walks a fixed list of probes in order. Each probe is fast, local, and side-effect free apart from two cheap HEAD requests at the end.

  1. lly on PATH. Resolves the lly binary, reports its absolute path and version. If you have two installs shadowing each other, this is where you see it.
  2. ~/.lly/ exists and is writable. The CLI keeps credentials, plugins, and caches under ~/.lly. Doctor stat-checks the directory and tries a temp-file write.
  3. Runtime present. The runtime plugin ships an embedded Wasmtime. Doctor invokes it with --versionand confirms the major matches the CLI's expected ABI.
  4. Plugins are executable. Every entry under ~/.lly/plugins/<name>/ is stat-checked for the executable bit and a trivial --lly-probe handshake.
  5. Signatures verify.Each installed plugin's manifest is re-verified against the RC signing key. A failure here means the binary on disk no longer matches what RC published.
  6. rc.lilylabs.io reachable. A single HEAD request to the registry. Confirms DNS, TLS, and the bucket origin.
  7. auth.lilylabs.io reachable. Another HEAD. Required for lly login to ever work.
  8. Credentials file mode is 0600. If ~/.lly/credentials exists, doctor checks it is owner-read-write only. A world-readable token is a finding, not a feature.

Reading the output

Doctor prints one line per probe with a leading glyph: green ✓ for passes, yellow ! for warnings, red ✗ for failures. The exit code is 0 if every probe passes or warns, and 1 if any probe fails. Warnings do not block the command.

doctor
$ lly doctor lly doctor v0.9.4 · 8 probes ✓ lly on PATH /usr/local/bin/lly · v0.9.4 ✓ ~/.lly writable /home/you/.lly · 0755 ✓ runtime present wasmtime 24.0.1 (embedded) ✓ plugins executable 4 found · nextjs, void, frontend-c, frontend-cpp ✓ signatures verify 4 / 4 manifests OK ✓ rc.lilylabs.io reachable HEAD 200 · 41 ms ✓ auth.lilylabs.io reachable HEAD 200 · 38 ms ! telemetry disabled config: telemetry = false ✓ credentials mode 0600 ~/.lly/credentials summary: 8 ok · 1 warn · 0 fail

The telemetry warning above is informational. Doctor flags it so you know reports will not include anonymous diagnostics, which makes triage harder if you later file a bug. Re-enable with lly config set telemetry true.

When something is actually broken

Failures look like this. Doctor keeps going so you see the full picture instead of bailing on the first red line.

doctor — failure
$ lly doctor ✓ lly on PATH /usr/local/bin/lly · v0.9.4 ✓ ~/.lly writable ✓ runtime present wasmtime 24.0.1 ✗ plugins executable nextjs: permission denied (mode 0644) ✗ signatures verify void: manifest hash mismatch ✓ rc.lilylabs.io reachable ✓ auth.lilylabs.io reachable ! credentials mode 0640 chmod 600 ~/.lly/credentials summary: 5 ok · 1 warn · 2 fail see: lly plugin verify · lly plugin reinstall <name>

Two failures, two fixes. A bad mode bit is a one-liner. A hash mismatch means the local binary drifted from its manifest, almost always because the file was modified on disk. Reinstall the plugin with lly plugin install <name> --force and re-run doctor.

Exit codes

  • 0 — all probes passed or warned.
  • 1 — at least one probe failed.
  • 2 — doctor itself could not start (broken install, missing $HOME).