forgeloop doctor

Usage

forgeloop doctor [--dir ./project] [--verbose] [--json] [--strict] [--fix] [--checks <groups>]

Doctor loads your ForgeLoop config from --dir (default: current working directory), then runs check groups and prints findings with errors, warnings, and optional info lines.

Default groups are config, structure, env, deps, and discord. network and tooling are opt-in.

Check groups

Group	What it covers
config	Handler path consistency for the selected preset
structure	Files expected for your manifest (aligned with the scaffold generator)
env	.env presence and required variables; placeholder / format hints
deps	package.json dependencies, node_modules, discord.js load probe, tsx for TypeScript
discord	(modular/advanced only) Command modules on disk and whether they load like forgeloop commands list
network	(opt-in) Reachability of Discord’s API (/gateway)
tooling	(opt-in) lint script when ESLint/Prettier or Biome is enabled

Default run includes: config, structure, env, deps, discord.
Add optional groups explicitly:

forgeloop doctor --checks config,structure,env,deps,discord,network,tooling

Exit codes

• 0 — No errors. Warnings do not fail the run unless --strict is set.
• 1 — One or more errors, or one or more warnings when --strict is set.

Parse errors or missing ForgeLoop config still throw a CliError (same as other commands).

Flags

Flag	Type	Default	Description
--dir	string	cwd	Project root to inspect.
--verbose	boolean	false	Print per-group “no findings” lines and issue evidence keys.
--json	boolean	false	Emit a JSON report to stdout (human banner/sections are skipped).
--strict	boolean	false	Treat warnings as failures (useful in CI).
--fix	boolean	false	Repair simple config exports, restore missing scaffold-managed files, merge missing package.json fields/scripts/deps, and create `.env` from `.env.example` when needed.
--checks	string	(default groups)	Comma-separated list of groups to run (see table above).

JSON output

--json prints a single object with:

• project — directory, name, preset, language, package manager, active config filename
• timestamp, durationMs
• summary — { errors, warnings, infos }
• issues[] — code, severity, group, title, message, fixes, optional evidence

Use it in CI:

forgeloop doctor --json --strict > doctor-report.json

If you also pass --fix, ForgeLoop prints fix notices to stderr while keeping JSON on stdout.

Related

No ForgeLoop config in directory:

No ForgeLoop project config found in …. Expected forgeloop.config.mjs.

See Workflow: doctor.