🚀 Pagecast: Streamline Your Markdown & HTML Publishing to Cloudflare Pages

Pagecast is a local-first utility designed specifically for deploying agent-generated reports and compact static web applications. It bridges the gap between local development (or AI generation) and shareable, live URLs via Cloudflare Pages.

📖 Overview

At its core, Pagecast provides a local administrative interface to preview your files, manage various published versions, customize link names, synchronize updates, and invalidate old URLs.

For those seeking automation, it offers:

Headless CLI: pagecast publish commands for terminal use.
Wrangler Abstraction: A simplified wrapper around the Cloudflare Pages CLI.
Agent Integration: Specialized skills for Codex and Claude agents.

🎯 Ideal Use Cases

Best suited for:

HTML Outputs: Dashboards, coverage reports, and results from Lighthouse or Playwright.

Markdown Documents: Project proposals, release notes, summaries, and general documentation.

Static Mini-Apps: Any project residing in folders like dist, out, build, or public.

AI Workflows: Coding agents that require a "human-in-the-loop" approval before pushing an artifact live.

Note: This is ~~not~~ intended for active Python, Ruby, or Node.js services unless they are first compiled into static assets.

The administrative UI is powered by React (built from web/ into public/) and comes pre-packaged.

🛠️ Installation & Execution

You can launch Pagecast instantly without a global installation using npx:

npx pagecast

🌐 Network Configuration

Pagecast operates using two distinct local servers. We can represent the port allocation as: $\text{Admin UI} = 4173 \quad \text{and} \quad \text{Preview Server} = 4174$

Admin UI (http://127.0.0.1:4173): Your primary hub for management.
Published-Page Server (http://127.0.0.1:4174): This server mimics the Cloudflare Pages URL structure (e.g., /p/slug/) to ensure previews are identical to the final deployment.
- Warning: The root path returns a 404. Use /healthz to verify the service is active.

Local Data Storage: All configurations and data are stored in the .pagecast/ directory within your current working folder.

Alternative Installation (from source):

git clone https://github.com/Amal-David/pagecast.git
cd pagecast
npm start

☁️ Cloudflare Integration

First-Time Setup Checklist

Run npx pagecast
Navigate to the Admin UI
Click "Connect Cloudflare"

Pagecast utilizes scoped Wrangler OAuth permissions: account:read, user:read, and pages:write. It will automatically detect your account and initialize the Pages project.

Alternative Setup Methods

Via Terminal: npx pagecast pages setup --project pagecast

Via API Token (for CI/CD): Create a token with Account Cloudflare Pages Edit permissions, then execute:

CLOUDFLARE_API_TOKEN=your_token_here npx pagecast pages status --json

Handling Multiple Accounts: If multiple accounts exist, select one via the UI or specify it in the command: npx pagecast pages setup --account <ACCOUNT_ID> --project pagecast

📤 Publishing Workflows

1. Publishing Single Files

You can push individual HTML or Markdown files directly to the cloud:

# Publish HTML
npx pagecast publish "/absolute/path/report.html" --json

# Publish Markdown
npx pagecast publish "/absolute/path/report.md" --json

Output: {"ok":true,"url":"https://project.pages.dev/p/token/", ...}

2. Publishing Static Project Snapshots

To share a build folder as a snapshot, build the project first, then publish the entry point:

npm run build
npx pagecast publish "$(pwd)/dist/index.html" --json

This method creates a /p/token/ link and automatically includes sibling assets from the build directory.

3. Full Site Deployment

To deploy an entire folder to a specific Cloudflare Pages project:

npx pagecast publish site "$(pwd)/dist" --project pagecasthq --branch main --json

(The --branch flag is optional; it defaults to main).

🔄 The Wrangler Abstraction

Pagecast simplifies the complex Wrangler deployment process.

~~CLOUDFLARE_ACCOUNT_ID=... npx wrangler pages deploy /path --project-name pagecasthq --branch main~~ $\rightarrow$ Use this instead: npx pagecast pages deploy "/path" --project pagecasthq --branch main --json

⚙️ Technical Reference

Deployment Logic Flow

Common Headless Errors

Status Code	Meaning	Resolution
`401`	Unauthorized	Run `npx pagecast pages setup` or connect via UI.
`409`	Conflict/Account Issue	Pass `--account <id>` or select account in UI.

Cloudflare Pages Command Suite

For automation and CI, always append the --json flag:

Setup: npx pagecast pages setup --project <name> --json
Status: npx pagecast pages status --json
List Projects: npx pagecast pages projects list --json
Deploy: npx pagecast pages deploy "/path/dist" --project <name> --json