Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/amal-david--pagecast/badge.svg)](/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

i

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.

  1. {
  2. "name": "pagecast",
  3. "owner": {
  4. "name": "Pagecast"
  5. },
  6. "metadata": {
  7. "description": "Publish agent-generated HTML or Markdown reports as Claude Code Artifacts or Pagecast Cloudflare Pages URLs."
  8. },
  9. "plugins": [
  10. {
  11. "name": "pagecast",
  12. "source": "./plugin",
  13. "description": "Asks whether to publish freshly created HTML/Markdown reports, plans, and docs as Claude Code Artifacts or Pagecast Cloudflare Pages URLs."
  14. }
  15. ]
  16. }
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.

  1. # Pagecast
  2. Preview local HTML reports, Markdown docs, and static mini apps, then publish
  3. them to shareable Cloudflare Pages URLs — from the terminal or your coding agent.
  4. **Site:** <https://pagecasthq.pages.dev/> ·
  5. **Agent skill:** [`publish-report` on Skills.sh](https://www.skills.sh/amal-david/pagecast/publish-report) ·
  6. **Architecture:** [ARCHITECTURE.md](ARCHITECTURE.md)
  7. <p align="center">
  8. <img src="media/admin.png" alt="Pagecast admin UI: published reports with per-page password protection" width="900">
  9. </p>
  10. Pagecast is a local-first publishing tool for agent-generated reports and small
  11. static web projects: preview files, publish, re-sync, rename links,
  12. password-protect pages, and revoke URLs — from a local admin UI or headless
  13. `pagecast` commands. Good fits: HTML reports and dashboards, Markdown docs and
  14. plans, static mini apps from `dist`/`build`/`out`. Not a fit: server-rendered
  15. apps that need a running backend (export static assets first).
  16. ## Quick Start
  17. Requires Node.js 20.19+ and a Cloudflare account (for publishing). No global install:
  18. ```sh
  19. npx pagecast
  20. ```
  21. This starts the local app and opens the admin UI:
  22. - Admin UI — `http://pagecast.localhost:4173`
  23. - Local preview/public origin — `http://pagecast.localhost:4174`
  24. - Pagecast Home — `~/.pagecast/home/` (Cloudflare target, publication registry, settings)
  25. - Workspace metadata — `.pagecast/` in the current directory
  26. One OS user profile owns one Pagecast Home and Cloudflare subdomain. Run the CLI
  27. from the relevant project; use `--data-dir` only for an intentionally isolated
  28. CI/container profile. If the default ports are busy, Pagecast falls forward to
  29. the next free pair and remembers it.
  30. In the admin UI, confirm the suggested Home subdomain and click **Connect
  31. Cloudflare** — Pagecast runs Wrangler's scoped browser OAuth flow (Cloudflare
  32. labels the app **Wrangler**) and resumes setup after consent. From a source
  33. checkout, run `npm start` instead. Prefer containers? See
  34. [Run with Docker](#run-with-docker).
  35. Run in the background, or (macOS) install a login service plus a local-only
  36. `http://pagecast.localhost` redirect:
  37. ```sh
  38. npx pagecast background start && npx pagecast open
  39. npx pagecast setup-local-url
  40. # manage: pagecast local-url status|remove, pagecast background service status|uninstall
  41. ```
  42. Headless/advanced setup:
  43. ```sh
  44. npx pagecast pages setup --project your-pagecast-home
  45. # multiple accounts? add --account <account-id>
  46. # automation? export CLOUDFLARE_API_TOKEN (scoped Pages:Edit) + CLOUDFLARE_ACCOUNT_ID
  47. ```
  48. **Upgrading from 0.5:** stop the old process (`npx pagecast@0.5.0 background stop`),
  49. reinstall the macOS login service if you use it (`npx pagecast@0.7.1 background
  50. service install`), and reload the unpacked Chrome extension from the matching
  51. release. The first 0.6 launch creates `~/.pagecast/home/` and imports compatible
  52. workspace publications without changing URLs; publications on other Cloudflare
  53. projects remain legacy targets until you explicitly attach or move them.
  54. After updating to 0.7.1, restart running Pagecast processes so they load the
  55. bundled staging cleanup helper. Saved publications and deployed copies are
  56. retained. Source checkouts must build the helper before starting Pagecast; see
  57. [Development](#development).
  58. ## Publish From The Terminal
  59. ```sh
  60. # An HTML or Markdown file → a memorable /p/<slug>/ link (source folder included)
  61. npx pagecast publish "/absolute/path/report.html" --json
  62. # Set an expiry — 7d, 12h, or never (default 30d)
  63. npx pagecast publish "/absolute/path/report.html" --expires 7d --json
  64. # Force a new URL, or explicitly update a known one
  65. npx pagecast publish "/absolute/path/report.html" --new-link --json
  66. npx pagecast publish "/absolute/path/report.html" --update <url-or-token> --json
  67. # A built static project → publish its entry file
  68. npm run build && npx pagecast publish ./dist/index.html --json
  69. # A whole folder → replace a named Pages project directly (--branch defaults to main)
  70. npx pagecast pages deploy ./dist --project my-static-site --json
  71. ```
  72. Things to know:
  73. - `publish` copies every non-hidden, non-symlink file under the source folder,
  74. referenced or not — publish from a clean folder and keep secrets elsewhere.
  75. New source copies are limited to **512 MiB and 10,000 files**, including files
  76. that grow while copying. Development roots (such as folders containing a
  77. package/build manifest, dependencies, Git repositories, or worktrees) are
  78. rejected before copying. Publish the finished `dist`/`build`/`out` folder or
  79. put a standalone report and its assets in a dedicated folder.
  80. - New links are **unlisted**: a memorable label plus a 128-bit suffix. Anyone
  81. with the URL can view it — unlisted is not private. The admin UI's **Short
  82. public link** toggle (or renaming to a vanity slug) makes a guessable public
  83. drop instead. Password protection is the access-control option.
  84. - Publishing is context-aware: repeating a publish for the same item in the same
  85. agent context updates the existing URL. Context comes from `--context-id`,
  86. `PAGECAST_CONTEXT_ID`, `CODEX_THREAD_ID`, `CLAUDE_SESSION_ID`, then a
  87. workspace/source fallback; override matching with `--new-link` or `--update`.
  88. - `pages deploy` is a separate, stateless whole-site operation on the named
  89. project. It never changes the project used for managed `/p/...` links —
  90. use a separate project unless replacing the managed site is intentional.
  91. - `statusCode 401` → authentication required (interactive runs start Wrangler
  92. auth automatically); `statusCode 409` → conflict, follow the returned message.
  93. ## Activity Analytics
  94. Optional, enabled in Settings: Pagecast deploys a Worker + D1 database to your
  95. Cloudflare account and shows views, anonymous uniques, and recent events beside
  96. each link, plus a global **Activity** view. Events carry coarse geo, device
  97. class, and referrer hostname; raw IPs are HMACed with a per-Home secret and
  98. discarded, and detailed events expire after 30 days. Analytics is audit
  99. visibility, not access control — use password protection to restrict access.
  100. ## Password Protection
  101. Gate any published page from the admin UI (**Password protection** toggle) or headlessly:
  102. ```sh
  103. npx pagecast publish "/absolute/path/report.html" --password "your-password" --json
  104. npx pagecast publish "/absolute/path/report.html" --no-password --json # remove it
  105. ```
  106. Enforced at the edge by a generated Cloudflare Pages Function covering every
  107. file of a multi-file report. Older immutable deployments keep the gate state
  108. they shipped with — prune deploy history if an unprotected snapshot must stop
  109. being reachable. Crypto and security model:
  110. [PASSWORD-PROTECTION.md](PASSWORD-PROTECTION.md).
  111. ## Deploy History
  112. Published reports send `X-Robots-Tag: noindex, nofollow` on static files and
  113. Function responses. This asks supporting search engines to exclude reports;
  114. it does not make links private. Use password protection for confidential content.
  115. Re-publish existing sites to apply these headers. Older deployment snapshots
  116. retain their original headers and must be pruned separately when needed.
  117. Do not block crawling with `robots.txt` if crawlers need to see `noindex`.
  118. Every publish or re-sync creates an immutable whole-site Cloudflare deployment
  119. with its own `<hash>.pages.dev` URL. Manage them from the admin UI
  120. (**Settings → Deploy history**) or the terminal:
  121. ```sh
  122. npx pagecast pages deployments list --json
  123. npx pagecast pages deployments delete <id> --json # the live deployment is protected
  124. npx pagecast pages deployments prune --keep 5 --yes --json
  125. ```
  126. Removing a snapshot never affects your live site or pages. But expiry, password
  127. changes, and revoke apply only to the replacement deployment — prune history
  128. when old snapshot URLs must stop working.
  129. Local temporary deployment directories are separate from this cloud history.
  130. While holding its workspace lease, Pagecast recovers abandoned staging at
  131. startup and before preparing another publication. It retains active owners and
  132. fresh interrupted operations for a 24-hour grace period. The staging tree
  133. stays in place while any operation is active, fresh, or unrecognized.
  134. Once the tree can be retired, recovery claims it before deleting
  135. old operations. The bundled cleanup helper removes entries relative to an
  136. opened staging directory and verifies its identity, so a replaced directory
  137. cannot redirect removal into saved publications or deployed copies. An
  138. interrupted claim is recovered on the next run. Cleanup
  139. failures are reported, recorded for retry, and block additional staging until removal
  140. succeeds. If recovery fails at startup, Pagecast warns and keeps the admin UI
  141. and read-only views available; legacy staging migration waits for successful
  142. recovery on a later startup. Saved publication snapshots and last-deployed
  143. copies are retained; failed source copies or direct-site deployments keep the
  144. last committed copy.
  145. ## Use From Coding Agents
  146. Pagecast ships a Codex-native skill and a portable Agent-Skills file. An
  147. explicit "Publish this as a Pagecast" instruction publishes immediately; a
  148. proactive agent suggestion still asks once.
  149. ```sh
  150. # Skills.sh (Codex, Claude Code, Cursor, Gemini CLI, and other supported agents)
  151. npx skills add https://github.com/amal-david/pagecast --skill publish-report
  152. # Claude Code plugin (includes the report-detection hook)
  153. /plugin marketplace add Amal-David/pagecast
  154. /plugin install pagecast@pagecast
  155. # Manual install from a clone
  156. cp -R .codex/skills/publish-report ~/.codex/skills/ # Codex
  157. cp plugin/skills/publish-report/SKILL.md /path/to/your-agent/skills/publish-report/SKILL.md # any agent
  158. ```
  159. More detail in [plugin/README.md](plugin/README.md).
  160. ## Use Through MCP
  161. Pagecast can run as a Model Context Protocol server, so MCP-capable agents can
  162. publish, inspect, and revoke through a bounded tool surface. Configure the stdio
  163. server:
  164. ```json
  165. {
  166. "mcpServers": {
  167. "pagecast": {
  168. "command": "npx",
  169. "args": ["pagecast", "mcp"]
  170. }
  171. }
  172. }
  173. ```
  174. It shares the same user-level Home, Cloudflare credentials, expiry, and
  175. password behavior as `npx pagecast publish`; add `"--data-dir"` only for an
  176. intentionally isolated MCP profile.
  177. | Tool | Purpose | Safety notes |
  178. | --- | --- | --- |
  179. | `status` | Show Cloudflare/Pagecast connection state. | Redacted by default; `verbose: true` only for trusted local clients. |
  180. | `list_pages` | List known reports and published links. | Redacted by default; `verbose: true` reveals local paths/build settings. |
  181. | `publish_content` | Publish supplied HTML or Markdown content. | Supports `mode: upsert\|new\|update`, `contextId`, `publication`; deterministic upserts need `itemKey`. |
  182. | `publish_file` | Publish a local `.html`/`.htm`/`.md`/`.markdown` file. | Isolates the entry file; sibling assets require `includeAssets: true` **and** `confirmAssets: true`. |
  183. | `revoke_publication` | Take a published token offline and redeploy. | Requires `confirm: true` because it changes a live URL. |
  184. The MCP server is separate from the admin API, which stays loopback-only — do
  185. not expose the admin port to a VPN or shared network. This release supports
  186. local stdio MCP only; an org-hosted HTTP endpoint would need its own auth,
  187. audit, and threat model, and a VPN would gate who can invoke Pagecast, not who
  188. can reach the published URL. Use password protection or your organization's
  189. access layer for restricted recipients.
  190. ## Run with Docker
  191. A single image bundles the whole `pagecast` CLI — it serves the admin dashboard
  192. and runs every publish/deploy command.
  193. ```sh
  194. # Serve the dashboard (then open http://localhost:4173)
  195. docker compose up --build
  196. # Or run the released image from GHCR
  197. docker pull ghcr.io/amal-david/pagecast:latest
  198. docker run --rm \
  199. -p 127.0.0.1:4173:4173 -p 127.0.0.1:4174:4174 \
  200. -v "$PWD/.pagecast:/app/.pagecast" \
  201. ghcr.io/amal-david/pagecast:latest serve
  202. ```
  203. Publishing from a container uses an API token, not the dashboard's OAuth
  204. button. Copy `.env.example` to `.env` with `CLOUDFLARE_API_TOKEN`
  205. (+ `CLOUDFLARE_ACCOUNT_ID`), or run headlessly:
  206. ```sh
  207. docker run --rm -v "$PWD:/work" -w /work \
  208. -e CLOUDFLARE_API_TOKEN -e CLOUDFLARE_ACCOUNT_ID \
  209. ghcr.io/amal-david/pagecast:latest publish ./report.html --json
  210. ```
  211. Notes:
  212. - The admin server can run build and publish commands, and its browser-mutation
  213. checks are not remote-user authentication. Always map both ports to the
  214. host's **loopback only** (`-p 127.0.0.1:4173:4173`, never bare `-p` mappings).
  215. - On Linux the container runs as uid 1000 (`node`); `mkdir -p .pagecast` before
  216. `compose up` (or `chown 1000:1000 .pagecast`) avoids bind-mount permission
  217. errors.
  218. - Wrangler is pinned (see `src/platform.js`) and baked into the image, so
  219. deploys don't contact npm at runtime.
  220. ## Chrome Extension (Experimental)
  221. > ⚠️ Experimental — load-unpacked only, not yet on the Chrome Web Store.
  222. When an agent opens an HTML file as `file:///…/report.html`, the bundled
  223. extension adds a one-click **Publish to Pagecast** button (the server must be
  224. running). Load `extension/` from a source checkout — or the
  225. `pagecast-extension-v<version>.zip` from the [matching release](https://github.com/Amal-David/pagecast/releases) —
  226. via `chrome://extensions` → **Developer mode** → **Load unpacked**, then enable
  227. **"Allow access to file URLs"**. See [extension/README.md](extension/README.md).
  228. ## Admin UI Features
  229. - Add `.html`/`.md` files by path or `file:///…` URL, deployable static folders,
  230. or source folders with a build command and output directory.
  231. - Drag to reorder; publish, re-sync in place, rename links (old links redirect;
  232. vanity slugs are public drops), or revoke one/all versions.
  233. - Auto-sync path-backed reports; password-protect pages; edit HTML in-app without
  234. touching the original source file.
  235. - Review interrupted managed operations and retry safe recovery steps.
  236. - View deploy history and remove old snapshots, with one-click "keep newest N" cleanup.
  237. ## Security Model
  238. - Admin UI binds to loopback by default, rejects non-loopback Host headers, and
  239. requires same-origin browser mutations plus a per-process CSRF token;
  240. no-Origin mutations require the private workspace capability.
  241. - Draft/report HTML is served only by the separate preview origin (port 4174),
  242. embedded by the admin origin in a sandbox without top-navigation permission.
  243. - The Chrome extension is limited to its session/status/local-publish routes.
  244. - Production access is through active `/p/<slug>/` links; revoked links 404
  245. after the replacement deploy. Older immutable deployment URLs retain their
  246. snapshot until pruned.
  247. - Public routes reject directory traversal and hidden files. CLI path publishing
  248. exposes every regular file under the report's source folder — keep secrets out.
  249. - The Pages root publishes no report listing.
  250. ## Telemetry
  251. Pagecast can collect **anonymous** usage stats — command name, Pagecast/Node
  252. version, OS/arch — never file contents, paths, URLs, or Cloudflare
  253. tokens/account IDs. Fresh interactive installs are opt-out with a one-time
  254. disclosure; telemetry is automatically off in CI. Exact fields:
  255. [PRIVACY.md](PRIVACY.md).
  256. ```sh
  257. npx pagecast telemetry status|disable|enable
  258. # env overrides: PAGECAST_TELEMETRY=0|1, DO_NOT_TRACK=1 (always wins)
  259. ```
  260. ## Development
  261. ```sh
  262. npm run build:native # build bundled staging cleanup helpers from source
  263. npm start # run the packaged app from source
  264. npm run check && npm test # verification suite
  265. npm run build # build cleanup helpers and the React admin UI
  266. ```
  267. Building or testing from source requires Go 1.25 or later; the build selects
  268. the pinned Go 1.27.2 toolchain. Published npm packages include cleanup binaries
  269. for macOS, Linux, and Windows on x64 and arm64. The Docker image includes its
  270. Linux binary. Neither installation needs Go at runtime.
  271. UI work requires pnpm 10: `pnpm -C web install --frozen-lockfile --ignore-scripts`,
  272. then `pnpm -C web run dev` (proxied to the server on 4173). The root CLI/server
  273. has no runtime npm dependencies. Layout: `src/` (CLI, server, publisher),
  274. `public/` (built UI), `web/` (React source), `plugin/` + `.codex/skills/`
  275. (agent skills), `test/` (Node tests). Source-folder build commands run through
  276. the platform's native shell (`sh -lc` / `%ComSpec%`) — author portable commands.
  277. ## Contributing
  278. Issues and pull requests are welcome. Fork and branch from `main`, keep the root
  279. CLI/server free of runtime npm dependencies, run `npm run check && npm test`
  280. before opening a PR, and rebuild the admin UI (`npm run build`) if you touched
  281. `web/`. Please **don't** file public issues for security problems — report them
  282. privately via [SECURITY.md](SECURITY.md).
  283. ## License
  284. MIT — see [LICENSE](LICENSE).
  285. ### Browser-native WebMCP publishing
  286. The local dashboard offers an opt-in WebMCP preview on supported Chrome builds.
  287. Agents can check publication capabilities and submit new HTML or Markdown; each
  288. publication requires source review and explicit confirmation before upload.
  289. The workflow reuses Pagecast's existing publisher and does not expose local
  290. files or paths. See [WebMCP setup, permissions and validation](WEBMCP.md).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.