pagecast
Publish HTML, Markdown and static mini apps to shareable Cloudflare Pages URLs from the terminal or coding agents.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/amal-david--pagecast)HTML
<a href="/listings/amal-david--pagecast"><img src="/api/listings/amal-david--pagecast/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
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-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 pagecast@0.5.0 background stop`), reinstall the macOS login service if you use it (`npx pagecast@0.7.0 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.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
.claude-plugin/marketplace.json · Manifest · 16 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- {
- "name": "pagecast",
- "owner": {
- "name": "Pagecast"
- },
- "metadata": {
- "description": "Publish agent-generated HTML or Markdown reports as Claude Code Artifacts or Pagecast Cloudflare Pages URLs."
- },
- "plugins": [
- {
- "name": "pagecast",
- "source": "./plugin",
- "description": "Asks whether to publish freshly created HTML/Markdown reports, plans, and docs as Claude Code Artifacts or Pagecast Cloudflare Pages URLs."
- }
- ]
- }
README.md · README · 367 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- # 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](https://www.skills.sh/amal-david/pagecast/publish-report) ·
- **Architecture:** [ARCHITECTURE.md](ARCHITECTURE.md)
- <p align="center">
- <img src="media/admin.png" alt="Pagecast admin UI: published reports with per-page password protection" width="900">
- </p>
- 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:
- ```sh
- 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-with-docker).
- Run in the background, or (macOS) install a login service plus a local-only
- `http://pagecast.localhost` redirect:
- ```sh
- 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:
- ```sh
- 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 pagecast@0.5.0 background stop`),
- reinstall the macOS login service if you use it (`npx pagecast@0.7.1 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](#development).
- ## Publish From The Terminal
- ```sh
- # 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:
- ```sh
- npx pagecast publish "/absolute/path/report.html" --password "your-password" --json
- npx pagecast publish "/absolute/path/report.html" --no-password --json # remove it
- ```
- Enforced at the edge by a generated Cloudflare Pages Function covering every
- file of a multi-file report. Older immutable deployments keep the gate state
- they shipped with — prune deploy history if an unprotected snapshot must stop
- being reachable. Crypto and security model:
- [PASSWORD-PROTECTION.md](PASSWORD-PROTECTION.md).
- ## Deploy History
- Published reports send `X-Robots-Tag: noindex, nofollow` on static files and
- Function responses. This asks supporting search engines to exclude reports;
- it does not make links private. Use password protection for confidential content.
- Re-publish existing sites to apply these headers. Older deployment snapshots
- retain their original headers and must be pruned separately when needed.
- Do not block crawling with `robots.txt` if crawlers need to see `noindex`.
- Every publish or re-sync creates an immutable whole-site Cloudflare deployment
- with its own `<hash>.pages.dev` URL. Manage them from the admin UI
- (**Settings → Deploy history**) or the terminal:
- ```sh
- npx pagecast pages deployments list --json
- npx pagecast pages deployments delete <id> --json # the live deployment is protected
- npx pagecast pages deployments prune --keep 5 --yes --json
- ```
- Removing a snapshot never affects your live site or pages. But expiry, password
- changes, and revoke apply only to the replacement deployment — prune history
- when old snapshot URLs must stop working.
- Local temporary deployment directories are separate from this cloud history.
- While holding its workspace lease, Pagecast recovers abandoned staging at
- startup and before preparing another publication. It retains active owners and
- fresh interrupted operations for a 24-hour grace period. The staging tree
- stays in place while any operation is active, fresh, or unrecognized.
- Once the tree can be retired, recovery claims it before deleting
- old operations. The bundled cleanup helper removes entries relative to an
- opened staging directory and verifies its identity, so a replaced directory
- cannot redirect removal into saved publications or deployed copies. An
- interrupted claim is recovered on the next run. Cleanup
- failures are reported, recorded for retry, and block additional staging until removal
- succeeds. If recovery fails at startup, Pagecast warns and keeps the admin UI
- and read-only views available; legacy staging migration waits for successful
- recovery on a later startup. Saved publication snapshots and last-deployed
- copies are retained; failed source copies or direct-site deployments keep the
- last committed copy.
- ## Use From Coding Agents
- Pagecast ships a Codex-native skill and a portable Agent-Skills file. An
- explicit "Publish this as a Pagecast" instruction publishes immediately; a
- proactive agent suggestion still asks once.
- ```sh
- # Skills.sh (Codex, Claude Code, Cursor, Gemini CLI, and other supported agents)
- npx skills add https://github.com/amal-david/pagecast --skill publish-report
- # Claude Code plugin (includes the report-detection hook)
- /plugin marketplace add Amal-David/pagecast
- /plugin install pagecast@pagecast
- # Manual install from a clone
- cp -R .codex/skills/publish-report ~/.codex/skills/ # Codex
- cp plugin/skills/publish-report/SKILL.md /path/to/your-agent/skills/publish-report/SKILL.md # any agent
- ```
- More detail in [plugin/README.md](plugin/README.md).
- ## Use Through MCP
- Pagecast can run as a Model Context Protocol server, so MCP-capable agents can
- publish, inspect, and revoke through a bounded tool surface. Configure the stdio
- server:
- ```json
- {
- "mcpServers": {
- "pagecast": {
- "command": "npx",
- "args": ["pagecast", "mcp"]
- }
- }
- }
- ```
- It shares the same user-level Home, Cloudflare credentials, expiry, and
- password behavior as `npx pagecast publish`; add `"--data-dir"` only for an
- intentionally isolated MCP profile.
- | Tool | Purpose | Safety notes |
- | --- | --- | --- |
- | `status` | Show Cloudflare/Pagecast connection state. | Redacted by default; `verbose: true` only for trusted local clients. |
- | `list_pages` | List known reports and published links. | Redacted by default; `verbose: true` reveals local paths/build settings. |
- | `publish_content` | Publish supplied HTML or Markdown content. | Supports `mode: upsert\|new\|update`, `contextId`, `publication`; deterministic upserts need `itemKey`. |
- | `publish_file` | Publish a local `.html`/`.htm`/`.md`/`.markdown` file. | Isolates the entry file; sibling assets require `includeAssets: true` **and** `confirmAssets: true`. |
- | `revoke_publication` | Take a published token offline and redeploy. | Requires `confirm: true` because it changes a live URL. |
- The MCP server is separate from the admin API, which stays loopback-only — do
- not expose the admin port to a VPN or shared network. This release supports
- local stdio MCP only; an org-hosted HTTP endpoint would need its own auth,
- audit, and threat model, and a VPN would gate who can invoke Pagecast, not who
- can reach the published URL. Use password protection or your organization's
- access layer for restricted recipients.
- ## Run with Docker
- A single image bundles the whole `pagecast` CLI — it serves the admin dashboard
- and runs every publish/deploy command.
- ```sh
- # Serve the dashboard (then open http://localhost:4173)
- docker compose up --build
- # Or run the released image from GHCR
- docker pull ghcr.io/amal-david/pagecast:latest
- docker run --rm \
- -p 127.0.0.1:4173:4173 -p 127.0.0.1:4174:4174 \
- -v "$PWD/.pagecast:/app/.pagecast" \
- ghcr.io/amal-david/pagecast:latest serve
- ```
- Publishing from a container uses an API token, not the dashboard's OAuth
- button. Copy `.env.example` to `.env` with `CLOUDFLARE_API_TOKEN`
- (+ `CLOUDFLARE_ACCOUNT_ID`), or run headlessly:
- ```sh
- docker run --rm -v "$PWD:/work" -w /work \
- -e CLOUDFLARE_API_TOKEN -e CLOUDFLARE_ACCOUNT_ID \
- ghcr.io/amal-david/pagecast:latest publish ./report.html --json
- ```
- Notes:
- - The admin server can run build and publish commands, and its browser-mutation
- checks are not remote-user authentication. Always map both ports to the
- host's **loopback only** (`-p 127.0.0.1:4173:4173`, never bare `-p` mappings).
- - On Linux the container runs as uid 1000 (`node`); `mkdir -p .pagecast` before
- `compose up` (or `chown 1000:1000 .pagecast`) avoids bind-mount permission
- errors.
- - Wrangler is pinned (see `src/platform.js`) and baked into the image, so
- deploys don't contact npm at runtime.
- ## Chrome Extension (Experimental)
- > ⚠️ Experimental — load-unpacked only, not yet on the Chrome Web Store.
- When an agent opens an HTML file as `file:///…/report.html`, the bundled
- extension adds a one-click **Publish to Pagecast** button (the server must be
- running). Load `extension/` from a source checkout — or the
- `pagecast-extension-v<version>.zip` from the [matching release](https://github.com/Amal-David/pagecast/releases) —
- via `chrome://extensions` → **Developer mode** → **Load unpacked**, then enable
- **"Allow access to file URLs"**. See [extension/README.md](extension/README.md).
- ## Admin UI Features
- - Add `.html`/`.md` files by path or `file:///…` URL, deployable static folders,
- or source folders with a build command and output directory.
- - Drag to reorder; publish, re-sync in place, rename links (old links redirect;
- vanity slugs are public drops), or revoke one/all versions.
- - Auto-sync path-backed reports; password-protect pages; edit HTML in-app without
- touching the original source file.
- - Review interrupted managed operations and retry safe recovery steps.
- - View deploy history and remove old snapshots, with one-click "keep newest N" cleanup.
- ## Security Model
- - Admin UI binds to loopback by default, rejects non-loopback Host headers, and
- requires same-origin browser mutations plus a per-process CSRF token;
- no-Origin mutations require the private workspace capability.
- - Draft/report HTML is served only by the separate preview origin (port 4174),
- embedded by the admin origin in a sandbox without top-navigation permission.
- - The Chrome extension is limited to its session/status/local-publish routes.
- - Production access is through active `/p/<slug>/` links; revoked links 404
- after the replacement deploy. Older immutable deployment URLs retain their
- snapshot until pruned.
- - Public routes reject directory traversal and hidden files. CLI path publishing
- exposes every regular file under the report's source folder — keep secrets out.
- - The Pages root publishes no report listing.
- ## Telemetry
- Pagecast can collect **anonymous** usage stats — command name, Pagecast/Node
- version, OS/arch — never file contents, paths, URLs, or Cloudflare
- tokens/account IDs. Fresh interactive installs are opt-out with a one-time
- disclosure; telemetry is automatically off in CI. Exact fields:
- [PRIVACY.md](PRIVACY.md).
- ```sh
- npx pagecast telemetry status|disable|enable
- # env overrides: PAGECAST_TELEMETRY=0|1, DO_NOT_TRACK=1 (always wins)
- ```
- ## Development
- ```sh
- npm run build:native # build bundled staging cleanup helpers from source
- npm start # run the packaged app from source
- npm run check && npm test # verification suite
- npm run build # build cleanup helpers and the React admin UI
- ```
- Building or testing from source requires Go 1.25 or later; the build selects
- the pinned Go 1.27.2 toolchain. Published npm packages include cleanup binaries
- for macOS, Linux, and Windows on x64 and arm64. The Docker image includes its
- Linux binary. Neither installation needs Go at runtime.
- UI work requires pnpm 10: `pnpm -C web install --frozen-lockfile --ignore-scripts`,
- then `pnpm -C web run dev` (proxied to the server on 4173). The root CLI/server
- has no runtime npm dependencies. Layout: `src/` (CLI, server, publisher),
- `public/` (built UI), `web/` (React source), `plugin/` + `.codex/skills/`
- (agent skills), `test/` (Node tests). Source-folder build commands run through
- the platform's native shell (`sh -lc` / `%ComSpec%`) — author portable commands.
- ## Contributing
- Issues and pull requests are welcome. Fork and branch from `main`, keep the root
- CLI/server free of runtime npm dependencies, run `npm run check && npm test`
- before opening a PR, and rebuild the admin UI (`npm run build`) if you touched
- `web/`. Please **don't** file public issues for security problems — report them
- privately via [SECURITY.md](SECURITY.md).
- ## License
- MIT — see [LICENSE](LICENSE).
- ### Browser-native WebMCP publishing
- The local dashboard offers an opt-in WebMCP preview on supported Chrome builds.
- Agents can check publication capabilities and submit new HTML or Markdown; each
- publication requires source review and explicit confirmation before upload.
- The workflow reuses Pagecast's existing publisher and does not expose local
- files or paths. See [WebMCP setup, permissions and validation](WEBMCP.md).
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.