Cloudflare Pages Deployment Status CLI

Status: Implemented

Owner: Symphony Core Systems Team

1. Problem

When code is pushed to master, Cloudflare Pages automatically builds and deploys the internal docs site (team.symphonycore.com). However, there is no visibility into whether a deployment succeeded or failed without manually logging into the Cloudflare dashboard. This creates several problems:

• Blind pushes. After pushing, developers have no local feedback on whether the site actually deployed.
• Slow failure detection. Build failures (e.g., dependency resolution errors, broken builds) go unnoticed until someone visits the dashboard or the site, which can be hours later.
• No log access from CLI. When a build does fail, diagnosing the issue requires navigating the Cloudflare UI to find build logs -- context-switching away from the terminal where the fix will be made.
• No scriptability. There is no way to programmatically check deployment status for automation, CI post-steps, or quick post-push verification.

2. Goal

Provide an automated, terminal-native way to check the status of production deployments on Cloudflare Pages, including build logs on failure, so developers get immediate feedback after pushing without leaving their workflow.

3. Success Criteria

Criteria	Measure
Deployment status is available from the CLI	npm run deploy-status returns status, stage, commit, URL, and duration
Build failures are diagnosable without the dashboard	Build logs auto-display on failure; available on-demand via --logs
No new runtime dependencies	Script uses only Node.js stdlib (https) + existing dotenv
Setup requires minimal effort	Single API token in .env.local; guided error messages for missing config
Works on Windows (cp1252)	ASCII-only output, no Unicode characters

4. Functional Requirements

4.1 Deployment Status Check

• FR-1: Query the Cloudflare Pages API for the latest production deployment.
• FR-2: Display deployment metadata: project name, status, current stage, environment, branch, commit hash + message, preview URL, creation timestamp, build duration, and deployment ID.
• FR-3: Indicate status with clear text labels: [OK] SUCCESS, [FAIL] FAILED, [...] IN PROGRESS, [??] <status>.
• FR-4: Exit code 0 on success, 1 on failure or in-progress, enabling use in scripts and CI.

4.2 Build Log Retrieval

• FR-5: Fetch build logs from the Cloudflare Pages deployment history API.
• FR-6: Auto-display build logs when the latest deployment has failed.
• FR-7: Support a --logs flag to display logs on-demand for any deployment state.
• FR-8: Format log output with timestamps (HH:MM:SS) and line content.

4.3 Error Handling & Guidance

• FR-9: On missing environment variables, print which variables are missing and step-by-step instructions for creating a Cloudflare API token.
• FR-10: On HTTP 401/403, advise that the token is invalid or expired with a link to the token creation page.
• FR-11: On HTTP 404, advise that the project name may be wrong and point to the config variable.
• FR-12: On network errors, suggest checking connectivity.

4.4 NPM Script Integration

• FR-13: Expose as npm run deploy-status (status check).
• FR-14: Expose as npm run deploy-logs (status + logs).

5. Non-Functional Requirements

• NFR-1: Zero external dependencies beyond Node.js stdlib and dotenv (already in the project).
• NFR-2: ASCII-safe output only -- no emoji or Unicode symbols (Windows cp1252 compatibility).
• NFR-3: Credentials stored in .env.local (gitignored), never committed.
• NFR-4: Guided self-service setup: error messages include exact steps to create and configure the API token.

6. Configuration

Variable	Source	Purpose
R2_ACCOUNT_ID	.env.local	Cloudflare account ID (shared with R2 media upload)
CLOUDFLARE_API_TOKEN	.env.local	API token with Cloudflare Pages:Read permission
CLOUDFLARE_PAGES_PROJECT	.env.local	Pages project name (default: symphonycore-docs)

Token creation: Cloudflare dashboard > Profile > API Tokens > Custom token > Account > Cloudflare Pages > Read.

7. Architecture

npm run deploy-status
        |
        v
scripts/deploy-status.js
        |
        |--> GET /client/v4/accounts/{id}/pages/projects/{name}/deployments
        |         (latest production deployment metadata)
        |
        |--> GET /client/v4/accounts/{id}/pages/projects/{name}/deployments/{id}/history/logs
        |         (build logs, on failure or --logs flag)
        |
        v
    Formatted terminal output + exit code

8. Deployment Pipeline Context

This tool monitors the following existing pipeline:

git push origin master
    --> GitHub Actions CI (typecheck, lint, build on Node 20)
    --> Cloudflare Pages auto-deploy (npm install + npm run build on Node 22)
    --> Live at team.symphonycore.com (behind Cloudflare Access OTP)

The deploy-status tool queries step 3 (Cloudflare Pages) for status and logs.

9. Files

File	Role
scripts/deploy-status.js	Main script (283 lines)
package.json	NPM script entries (deploy-status, deploy-logs)
.env.example	Documents required environment variables
.env.local	Actual credentials (gitignored)