Flisk Doctor

---
name: flisk-doctor
description: Check or repair the local Flisk development environment and project configuration using `flisk doctor` (including `--all`, `--json` and `--fix`). Use when setting up a Flisk project, before running `flisk up`, or when Docker, Tilt, Bun, ports, Docker networks, generated files or service manifests may be misconfigured. For a stack that started and then failed, use flisk-troubleshoot instead.
license: MIT
compatibility: Requires the flisk CLI, Docker and Tilt on the local machine. Does not deploy.
metadata:
  author: flisk-sh
  version: "1.0"
---

# Flisk doctor

Use the CLI's environment and project checks as the starting point for Flisk setup and diagnosis.

## Workflow

1. Run `flisk doctor` from the Flisk project root.
2. Read the full output and distinguish host prerequisites from project configuration findings.
3. Fix the source configuration or environment item named by the diagnostic. Do not hand-edit generated `.autogenerated/` output.
4. Run `flisk doctor` again to confirm the finding is resolved.
5. Before starting services, use `flisk networks` to inspect the routed URLs; start only the needed stack with `flisk up <stack>` when appropriate.

## When the standard check is not enough

`flisk doctor` has no `--verbose` flag of its own. Use these instead:

- `flisk doctor --all` runs every check and prints the Machine and Project sections with a summary.
- `flisk doctor --json` prints the versioned readiness report: each check's name, result, message and fix. Read it instead of parsing the human output.
- `flisk doctor --no-ping` skips pinging the `/health` of running services; `--ping-timeout <ms>` gives slow services longer.
- `flisk doctor --strict` fails on warnings too, such as a WSL project under `/mnt/c`.
- `flisk config verify --json` checks that the generated files match `.flisk/project.json` and every `service.json`. Doctor checks the machine and the services; `config verify` checks generated-file consistency.
- `FLISK_VERBOSE=1` prints error details that some commands (for example `flisk networks` and `flisk upgrade`) otherwise hide.
- `FLISK_DEBUG=1 flisk up --verbose` adds the engine's Starlark debug logs to the Tilt output.

## Repairs

- `flisk doctor --fix --dry-run` lists the repairs without changing anything. `flisk doctor --fix` applies them after asking (`--yes` skips the question). It removes this project's unused Docker networks and leftover doctor probes.
- When Docker refuses new networks (`all predefined address pools have been fully subnetted`), run `flisk doctor --fix --scope=machine`. It also removes the unused networks of other Flisk projects, and skips any network a container is attached to.

## Guardrails

- Do not claim the project is ready when `flisk doctor` reports unresolved errors.
- The exit code of `flisk doctor --json` reflects the host state; read the report, not only the exit code.
- Ask before starting a large landscape or a task likely to build or launch many containers; it can take several minutes and use substantial resources.
- Avoid stopping containers by broad name patterns. Identify the target project and stack first.
- Treat diagnostic output as evidence. If it does not identify a cause, report what was observed and gather the next relevant check instead of guessing.