Diagnostic Command

Updated on Oct 1, 2026

frg diagnose checks whether Forge is ready to run in the current project and collects diagnostic data for troubleshooting or a support request. It runs offline (no network authentication probes) and does not need a license or a working agent, so you can use it when other commands fail.

Prerequisites

• Forge installed. No license, coding agent, or work-item context is required.
• Run the command from the project directory you want to check.

Subcommands at a glance

frg diagnose has no subcommands. Choose a mode with options:

Mode	What it does	Typical inputs	Outputs
frg diagnose	Readiness report for the terminal	Project and user configuration	Human-readable report on stdout
frg diagnose --format json	Same report as JSON	Project and user configuration	JSON on stdout
frg diagnose --bundle	Support bundle archive	Configuration, plus logs and traces when requested	frg-diagnose-<YYYYMMDD>-<HHMMSS>.tar.gz in the current directory, or the --output path
--include-logs, --include-traces	Adds runtime files from the last 24 hours	Forge log and trace files	Included in the bundle

Typical flow

text

frg diagnose ──► fix failed checks ──► frg diagnose ──► still failing? ──► frg diagnose --bundle --include-logs --include-traces ──► review ──► share

1. Check readiness:

bash

frg diagnose

2. Fix each FAIL check using the suggestion shown under it, then run frg diagnose again.
3. If the problem persists, create a support bundle with recent logs and traces:

bash

frg diagnose --bundle --include-logs --include-traces --output ./frg-support.tar.gz

4. Inspect the bundle before you share it:

bash

tar tzf ./frg-support.tar.gz

frg diagnose

text

frg diagnose [OPTIONS]

Option	Description	Default
--format <FORMAT>	Output format: human or json.	human
--bundle	Generates a support bundle archive (.tar.gz).	Off
-o, --output <PATH>	Output path for the bundle. The file must not already exist.	frg-diagnose-<timestamp>.tar.gz in the current directory
--include-traces	Includes trace files from the last 24 hours.	Off
--include-logs	Includes log files from the last 24 hours.	Off
-v, --verbose	Includes detailed file paths and timing information.	Off
-q, --quiet	Suppresses all output except errors.	Off

Examples:

bash

frg diagnose --format json > diagnostic.json
frg diagnose --verbose
frg diagnose --bundle --include-logs

Report contents

The report shows the schema version (1.0.0), Forge version, collection mode (offline), an overall readiness status, and one check per category (for example initialization, agent, toolchain) with level pass or fail, a message, and a suggestion.

Example output (abbreviated, from a project without an agent or toolchain.toml):

json

{
 "version": "1.0.0",
 "status": "Error",
 "forge_version": "4.6.0",
 "collection_mode": "offline",
 "status_checks": [
 { "category": "initialization", "level": "pass", "message": "Project initialized at ." },
 { "category": "toolchain", "level": "fail",
 "message": "toolchain.toml is missing (REQUIRED)",
 "suggestion": "Run 'frg config init --issues <tool> --code <tool>' to create toolchain.toml" }
 ],
 "warnings": [],
 "collection_stats": { "files_scanned": 0, "files_collected": 0, "files_skipped": 0, "bytes_collected": 0 }
}

Support bundles

A bundle contains:

• diagnostic.json: the report above.
• manifest.json: an inventory of the bundle.
• The selected log and trace files, when you pass --include-logs or --include-traces.

Diagnostic output redacts detected tokens, keys, secrets, and passwords, and runtime files are size-limited. Review the bundle before sharing it; it can still contain project names, paths, and prompts.

Exit codes

Code	Meaning
0	Collection completed, whatever the readiness status (a report with status Error still exits 0).
4	Invalid diagnostic arguments, for example --format xml.
Non-zero	Collection or output failed, for example when the bundle path already exists.

Troubleshooting

Invalid diagnostic arguments: Validation error: Invalid format: xml. Use 'human' or 'json'.

Cause: --format has a value other than human or json.

Solution: Run frg diagnose --format json or frg diagnose --format human.

Output file already exists: . Use --output to specify a different path.

Cause: --bundle never overwrites an existing file.

Solution:

1. Choose a new path: frg diagnose --bundle --output ./frg-support-2.tar.gz, or
2. Remove the old archive first.

The bundle contains no logs or traces

Cause: Logs and traces are opt-in, and only files from the last 24 hours are collected.

Solution: Add --include-logs --include-traces, and reproduce the problem shortly before you create the bundle.

See Also

• Utility Commands
• Common Issues.
• Agent Troubleshooting.
• Transaction Logs.
• Command Reference.