Pagecast

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.

Site: https://pagecasthq.pages.dev/ · Agent skill: publish-report on Skills.sh · Architecture: ARCHITECTURE.md

Pagecast is a local-first publishing tool for agent-generated reports and small static web projects: preview files, publish, re-sync, rename links, password-protect pages, and revoke URLs — from a local admin UI or headless pagecast commands. Good fits: HTML reports and dashboards, Markdown docs and plans, static mini apps from dist/build/out. Not a fit: server-rendered apps that need a running backend (export static assets first).

Quick Start

Requires Node.js 20.19+ and a Cloudflare account (for publishing). No global install:

npx pagecast

This starts the local app and opens the admin UI:

• Admin UI — http://pagecast.localhost:4173
• Local preview/public origin — http://pagecast.localhost:4174
• Pagecast Home — ~/.pagecast/home/ (Cloudflare target, publication registry, settings)
• Workspace metadata — .pagecast/ in the current directory

One OS user profile owns one Pagecast Home and Cloudflare subdomain. Run the CLI from the relevant project; use --data-dir only for an intentionally isolated CI/container profile. If the default ports are busy, Pagecast falls forward to the next free pair and remembers it.

In the admin UI, confirm the suggested Home subdomain and click Connect Cloudflare — Pagecast runs Wrangler's scoped browser OAuth flow (Cloudflare labels the app Wrangler) and resumes setup after consent. From a source checkout, run npm start instead. Prefer containers? See Run with Docker.

Run in the background, or (macOS) install a login service plus a local-only http://pagecast.localhost redirect:

npx pagecast background start && npx pagecast open
npx pagecast setup-local-url
# manage: pagecast local-url status|remove, pagecast background service status|uninstall

Headless/advanced setup:

npx pagecast pages setup --project your-pagecast-home
# multiple accounts? add  --account <account-id>
# automation? export CLOUDFLARE_API_TOKEN (scoped Pages:Edit) + CLOUDFLARE_ACCOUNT_ID

Upgrading from 0.5: stop the old process (npx [email protected] background stop), reinstall the macOS login service if you use it (npx [email protected] background service install), and reload the unpacked Chrome extension from the matching release. The first 0.6 launch creates ~/.pagecast/home/ and imports compatible workspace publications without changing URLs; publications on other Cloudflare projects remain legacy targets until you explicitly attach or move them.

After updating to 0.7.1, restart running Pagecast processes so they load the bundled staging cleanup helper. Saved publications and deployed copies are retained. Source checkouts must build the helper before starting Pagecast; see Development.

Publish From The Terminal

# An HTML or Markdown file → a memorable /p/<slug>/ link (source folder included)
npx pagecast publish "/absolute/path/report.html" --json

# Set an expiry — 7d, 12h, or never (default 30d)
npx pagecast publish "/absolute/path/report.html" --expires 7d --json

# Force a new URL, or explicitly update a known one
npx pagecast publish "/absolute/path/report.html" --new-link --json
npx pagecast publish "/absolute/path/report.html" --update <url-or-token> --json

# A built static project → publish its entry file
npm run build && npx pagecast publish ./dist/index.html --json

# A whole folder → replace a named Pages project directly (--branch defaults to main)
npx pagecast pages deploy ./dist --project my-static-site --json

Things to know:

• publish copies every non-hidden, non-symlink file under the source folder, referenced or not — publish from a clean folder and keep secrets elsewhere. New source copies are limited to 512 MiB and 10,000 files, including files that grow while copying. Development roots (such as folders containing a package/build manifest, dependencies, Git repositories, or worktrees) are rejected before copying. Publish the finished dist/build/out folder or put a standalone report and its assets in a dedicated folder.
• New links are unlisted: a memorable label plus a 128-bit suffix. Anyone with the URL can view it — unlisted is not private. The admin UI's Short public link toggle (or renaming to a vanity slug) makes a guessable public drop instead. Password protection is the access-control option.
• Publishing is context-aware: repeating a publish for the same item in the same agent context updates the existing URL. Context comes from --context-id, PAGECAST_CONTEXT_ID, CODEX_THREAD_ID, CLAUDE_SESSION_ID, then a workspace/source fallback; override matching with --new-link or --update.
• pages deploy is a separate, stateless whole-site operation on the named project. It never changes the project used for managed /p/... links — use a separate project unless replacing the managed site is intentional.
• statusCode 401 → authentication required (interactive runs start Wrangler auth automatically); statusCode 409 → conflict, follow the returned message.

Activity Analytics

Optional, enabled in Settings: Pagecast deploys a Worker + D1 database to your Cloudflare account and shows views, anonymous uniques, and recent events beside each link, plus a global Activity view. Events carry coarse geo, device class, and referrer hostname; raw IPs are HMACed with a per-Home secret and discarded, and detailed events expire after 30 days. Analytics is audit visibility, not access control — use password protection to restrict access.

Password Protection

Gate any published page from the admin UI (Password protection toggle) or headlessly:

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗