gtapps/forge-logs

Forge Logs

Read deployment and server logs from Forge.

---

Latest deployment log for a site

php ${CLAUDE_PLUGIN_ROOT}/php/forge.php logs <server> <site>

Fetches the most recent deployment and returns its full log.

Specific deployment log

php ${CLAUDE_PLUGIN_ROOT}/php/forge.php deploy-log <server> <site> <deploy-id>

Use deploy-history first to find the deployment ID.

Server log

php ${CLAUDE_PLUGIN_ROOT}/php/forge.php server-log <server> <key>

Common keys: php, mysql, cron, daemon, nginx-error, nginx-access. Nginx keys are hyphenated; nginx_error (underscored) returns a 404. The PHP-FPM log key is dot-version notation matching the server's installed PHP (php-8.3, not php) — passing the literal php key auto-resolves it against the server's php_version. mysql/cron/daemon may 404 outright on servers with a custom, non-Forge-provisioned install of that service (no Forge-tracked log path) — a 404 there isn't necessarily a wrong key. Key list depends on the server's installed services.

Site logs

php ${CLAUDE_PLUGIN_ROOT}/php/forge.php site-log <server> <site> <type>

<type> is one of application (the Laravel app log), nginx-access, nginx-error. Application and access logs leak PII and tokens more readily than deploy logs — the Secret hygiene rules below apply with extra force.

Background process log

php ${CLAUDE_PLUGIN_ROOT}/php/forge.php background-process-log <server> <process-id>

The log path for apps that run as a Forge Background Process instead of PHP-FPM (Node apps, queue workers, custom daemons). server-log does not cover these. Find the process ID first:

echo '[<server-id>]' | php ${CLAUDE_PLUGIN_ROOT}/php/forge.php call backgroundProcesses

---

Triage mode

When the operator says something like "what's wrong with myapp.com" or "triage the failing site", bundle context automatically:

1. php ${CLAUDE_PLUGIN_ROOT}/php/forge.php site <server> <site> — confirm the site is reachable and check status fields.
2. php ${CLAUDE_PLUGIN_ROOT}/php/forge.php deploy-history <server> <site> — surface the last few deployments and their statuses.
3. php ${CLAUDE_PLUGIN_ROOT}/php/forge.php logs <server> <site> — fetch the latest deployment log.
4. Synthesize: identify the failure type (build error, composer error, migration error, timeout), highlight the relevant log section, and suggest a remedy.

---

Secret hygiene

Deployment and server logs may contain env dumps, database credentials, and API keys. Apply these rules to every log-reading flow:

• Never paste raw log output into the channel. Always summarize or excerpt.
• Never write raw log content to compiled/ or raw/ — scrub any credential values to [REDACTED] before persistence.
• If asked to share a log, review it first and redact any secret-pattern lines.

---

Notes

• <server> and <site> accept name, hostname, or numeric ID.
• For a failed deployment you triggered via forge-deploy, the deploy-incident artifact (written by forge-deploy when its watch Monitor sees a failed terminal status) already contains the scrubbed log tail — check compiled/deploy-incident-<site>-<date>.md before re-fetching.
• Other output reads (commandOutput, scheduledJobOutput, siteScheduledJobOutput, serverEventOutput) are reachable via call <method> with JSON args on stdin; their content comes back JSON-encoded.