| name | forge-logs |
| description | Read site deployment logs, server logs, site application/nginx logs, background process logs, and specific deployment logs from Laravel Forge. Includes a triage mode that bundles recent logs with deployment history for rapid incident analysis. Triggers on "show logs", "read logs", "deployment log", "server log", "what happened to the deployment", "triage failing site". |
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:
php ${CLAUDE_PLUGIN_ROOT}/php/forge.php site <server> <site> — confirm the site is reachable and check status fields.php ${CLAUDE_PLUGIN_ROOT}/php/forge.php deploy-history <server> <site> — surface the last few deployments and their statuses.php ${CLAUDE_PLUGIN_ROOT}/php/forge.php logs <server> <site> — fetch the latest deployment log.- 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.
