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.