Collect Diagnostic Logs

Before contacting support, collect the diagnostic information below. A complete report helps us resolve your issue in one exchange rather than several back-and-forth questions.

---

What to Collect

1. Debug log from the failing command

Run the command that is failing with debug logging enabled, redirecting stderr to a file:

FORGE_LOG=debug forge index . 2>forge-debug.log

Or for MCP server issues:

FORGE_LOG=debug forge serve /path/to/repo 2>forge-serve-debug.log

For one-off command failures:

FORGE_LOG=debug forge health --repo . 2>forge-health-debug.log

The 2> redirects Forge’s log output (which goes to stderr) to a file, leaving stdout clean.

2. Index status

forge status --repo . > forge-status.txt 2>&1

This shows file count, last index timestamp, stale files, and whether the search index and git history are available.

3. License status

forge license > forge-license.txt 2>&1

This shows your tier, masked email, features, and expiration date. Your full email address is never printed — only a masked version like p***[email protected].

4. Usage statistics

forge stats --json > forge-stats.json 2>&1

This shows tool call counts, average latencies, and recent health check history. All data is local — it has never been transmitted anywhere.

5. Forge version

forge --version

Include the version string in your support email even if it is also in the debug log.

6. Heartbeat status (for license issues)

forge config heartbeat show > forge-heartbeat.txt 2>&1

This shows the last heartbeat timestamp, cached status, and next scheduled attempt. Nothing is transmitted by running this command.

---

What to Redact Before Sending

Review the files before attaching them to a support request:

In forge-debug.log / forge-serve-debug.log:

• Search for file paths that contain personal directory names you do not want to share: grep -n "home/username" forge-debug.log
• Remove any lines containing internal API keys or tokens if they appear (this would be a separate security concern — contact us separately if you see credentials in logs)
• Repository names and file paths are generally safe to share with support

In forge-stats.json:

• This file contains only tool call counts and latencies. It does not contain file names, symbols, or queries. No redaction is typically needed.

In forge-license.txt:

• Your email address is already masked by Forge (e.g., p***[email protected]). No redaction needed.

Do not share:

• Your raw license key string
• Your Stripe payment information
• Any source code you do not want Ironpine Labs to see (diagnostic logs do not contain source code, but be aware of any custom scripts you might attach)

---

How to Send

Email support at [email protected] with:

Subject line: Brief description of the issue (e.g., “forge activate: InvalidSignature on fresh key”)

Body:

• One-paragraph description of the problem: what you did, what you expected, what happened instead
• Platform (macOS Apple Silicon / macOS Intel / Linux x86-64 / Linux ARM64 / Windows)
• Whether this was working before and what changed (new install, recent update, new repo, etc.)

Attachments:

• forge-debug.log (or the relevant debug log file)
• forge-status.txt
• forge-license.txt
• forge-stats.json (optional but helpful for performance issues)
• forge-heartbeat.txt (for license/activation issues)

---

Quick Reference: All Diagnostic Commands

# 1. Debug log
FORGE_LOG=debug forge <failing-command> 2>forge-debug.log

# 2. Index status
forge status --repo . > forge-status.txt 2>&1

# 3. License status
forge license > forge-license.txt 2>&1

# 4. Usage stats
forge stats --json > forge-stats.json 2>&1

# 5. Version
forge --version

# 6. Heartbeat status (license issues only)
forge config heartbeat show > forge-heartbeat.txt 2>&1

Run all of these before sending a support request. Attach the .txt, .log, and .json files.