GitHub - Amal-David/pagecast: Publish local HTML, Markdown, and static mini apps to shareable Cloudflare Pages URLs from the terminal or coding agents.
Pangram verdict · v3.3
We believe that this document is a mix of AI-generated, AI-assisted, and human-written content
AI likelihood · overall
MixedArticle text · 1,279 words · 6 segments analyzed
Preview local HTML reports, Markdown docs, and static mini apps, then publish them to shareable Cloudflare Pages URLs from the terminal or your coding agent. Live app: https://pagecasthq.pages.dev/ About Pagecast is a local-first publishing tool for agent-generated reports and small static web projects. It gives you a local admin UI for previewing files, managing published versions, renaming links, re-syncing updates, and revoking old URLs. For automation, it exposes headless pagecast publish commands, a small Cloudflare Pages CLI abstraction, and Codex / Claude agent skills. Good fits:
HTML reports, dashboards, coverage output, Playwright or Lighthouse reports. Markdown plans, proposals, release notes, docs, and summaries. Static mini apps from build folders such as dist, build, out, or public. Coding-agent workflows that should ask before publishing a finished artifact.
Not a fit:
Private drafts or scratch notes. Server-rendered apps that need a running backend. Python/Ruby/Node services unless they first export static assets.
Requirements
Node.js 20 or newer. npx for one-command use. A Cloudflare account for public publishing. pnpm only when rebuilding the web UI from web/.
The root CLI/server has no runtime npm dependencies. The React admin UI is built from web/ into public/ and is already included in the package. Install And Run Use Pagecast without installing it globally: npx pagecast This starts the local app and opens the admin UI.
Admin UI: http://127.0.0.1:4173 Local published-page server: http://127.0.0.1:4174 Local data/config: .pagecast/ in your current working directory
Use the admin UI on 4173 for normal work. The 4174 server is intentionally separate: it serves local published-page routes such as /p/<slug>/ so Pagecast can preview the same URL shape it deploys to Cloudflare Pages. Its root path is not an app and returns 404; use /healthz only to check that it is running.
From a clone: git clone https://github.com/Amal-David/pagecast.git cd pagecast npm start First-Time Cloudflare Setup Run the app once: npx pagecast Open the Cloudflare Pages panel and click Connect Cloudflare. Pagecast uses scoped Wrangler OAuth (account:read, user:read, pages:write), detects your account, and creates the Pages project if needed. Or do the same setup from the terminal: npx pagecast pages setup --project pagecast If you prefer a token for automation, create a scoped Cloudflare API token with Account > Cloudflare Pages > Edit permission, then run: CLOUDFLARE_API_TOKEN=... CLOUDFLARE_ACCOUNT_ID=... npx pagecast pages status --json If more than one Cloudflare account is available, Pagecast asks you to choose the account once in the admin UI, or you can pass it directly: npx pagecast pages setup --account 90e4c638bea527f464ec6fa7caebfd4e --project pagecast Publish From The Terminal Publish an HTML file: npx pagecast publish "/absolute/path/report.html" --json # -> {"ok":true,"url":"https://<project>.pages.dev/p/<token>/", ...} Publish Markdown: npx pagecast publish "/absolute/path/report.md" --json Publish a static web project as a shareable snapshot by building first, then publishing the generated entry file: npm run build npx pagecast publish "$(pwd)/dist/index.html" --json This creates a /p/<token>/ link and stages sibling assets from the build folder. Deploy a whole static folder directly to a named Cloudflare Pages project: npx pagecast publish site "$(pwd)/dist" --project pagecasthq --branch main --json --branch is optional.
If you omit it, Pagecast deploys to main: npx pagecast pages deploy "$(pwd)/dist" --project pagecasthq --json That command is the Pagecast abstraction over raw Wrangler deploys. It replaces: CLOUDFLARE_ACCOUNT_ID=90e4c638bea527f464ec6fa7caebfd4e npx wrangler pages deploy /private/tmp/pagecasthq-deploy --project-name pagecasthq --branch main with: npx pagecast pages deploy /private/tmp/pagecasthq-deploy --project pagecasthq --branch main --json Direct site deploys replace the target Pages project contents. For source-folder build settings, link renaming, re-sync, and revoke controls, use the app: npx pagecast Common headless errors:
{"ok":false,"statusCode":401}: run npx pagecast pages setup once, or run npx pagecast and connect Cloudflare. {"ok":false,"statusCode":409}: pass --account <account-id>, or run npx pagecast once and choose the Cloudflare account.
Cloudflare Pages Commands Pagecast wraps the Wrangler commands needed for normal Pages publishing: npx pagecast pages setup --project pagecast --json npx pagecast pages status --json npx pagecast pages projects list --json npx pagecast pages deploy "/absolute/path/dist" --project pagecasthq --branch main --json npx pagecast pages deploy "/absolute/path/dist" --project pagecasthq --json Agents and CI should prefer --json. Human terminal output stays concise by default. Direct deploys use main when --branch is not provided. Chrome Extension (Local to Public) When an agent writes an HTML file and opens it as file:///…/report.html, the bundled Chrome extension adds a one-click Publish to Pagecast button. It publishes the local file through your running Pagecast server and returns a public link; re-publishing the same file updates the same URL. Install (load unpacked):
chrome://extensions → enable Developer mode → Load unpacked → select the extension/ folder. Open the extension's Details and enable "Allow access to file URLs".
Run npx pagecast (connected to Cloudflare), open a local .html/.md file, click the toolbar icon → Publish.
The server must be running (a browser extension can't start it). The admin server exposes a POST /api/publish-local { path } endpoint and reflects CORS only for chrome-extension:// origins. See extension/README.md for details. Use From Codex And Other Agents Pagecast includes a Codex-native skill and a portable Agent-Skills file. The skill tells the agent to offer once for finished, shareable HTML/Markdown/static artifacts and to publish only after explicit confirmation. Codex CLI Or Codex Desktop From a clone of this repo: mkdir -p ~/.codex/skills cp -R .codex/skills/publish-report ~/.codex/skills/ Start a new Codex session, then ask: Use $publish-report to publish /absolute/path/report.md with Pagecast.
For a web project: Use $publish-report to build this project and publish dist/index.html with Pagecast.
Claude Code /plugin marketplace add Amal-David/pagecast /plugin install pagecast@pagecast This installs the portable publish-report skill and the Claude Code report-detection hook. Other Agent-Skills Tools Copy the portable skill into your agent's skills folder: cp plugin/skills/publish-report/SKILL.md /path/to/your-agent/skills/publish-report/SKILL.md More detail is in plugin/README.md. Admin UI Features
Add .html, .htm, .md, and .markdown files by absolute path or file:///... URL. Add deployable static folders. Add source folders with an explicit build command and output directory. Drop or choose HTML/Markdown files and browser-supported folder uploads. Drag to reorder reports. Publish a shareable URL, revoke one version, or revoke all versions for a report. Rename a published URL. Old links redirect to the new path. Re-sync a published page in place at the same URL. Enable auto-sync for path-backed reports. Edit HTML in the app without overwriting the original source file.
Local Development Run the packaged app from source: npm start Run the verification suite: npm run check npm test Rebuild the React admin UI into public/: npm run build Work on the React UI with Vite: pnpm -C web install --frozen-lockfile --ignore-scripts npm start pnpm -C web run dev Vite runs on http://127.0.0.1:5173 and proxies /api, /preview, and /p to the local Pagecast server on http://127.0.0.1:4173. Project Layout src/ Node CLI, server, Cloudflare Pages publisher public/ Built admin UI served by the package web/ Vite + React source for the admin UI plugin/ Claude/portable Agent-Skills integration .codex/skills/publish-report/ Codex-native Pagecast skill llms.txt Agent-readable command and workflow map test/ Node test suite
Packaging And Release Checks Before publishing a package: npm run build npm run check npm test npm pack --dry-run The npm package includes src/, public/, plugin/, llms.txt, and the Codex skill under .codex/skills/publish-report/. Security Model
The admin UI binds to 127.0.0.1. Draft previews are admin-only local routes. Public access works only through active /p/<token>/ publication links. Revoked publication tokens return 404 after the Pages redeploy finishes.
Public report routes reject parent-directory traversal and hidden-file paths. Path-based reports and snapshots include non-hidden sibling assets from the report folder, so anything in that folder can become public if referenced or guessed. The Pages root does not publish a report listing.
License Pagecast is released under the MIT License. See LICENSE. Contributing Issues and pull requests are welcome. Keep changes focused, run the verification commands above, and rebuild public/ with npm run build whenever you change files under web/.