pushdraft

Pushdraft is the open-source alternative to postplan.dev for publishing versioned drafts. The entire server, API and CLI codebase is public, and drafts can be protected with authentication.

Production runs at https://draft.shubrt.me, with drafts on wildcard subdomains (*.draft.shubrt.me). The draft.shubrt.me record may be proxied, but the *.draft and _acme-challenge.draft records must be DNS-only because Cloudflare Universal SSL does not cover the second-level wildcard *.draft.shubrt.me, so Railway issues that certificate, as it does for preview domains. The former domain pushdraft.dev is no longer a Railway custom domain. Its records stay proxied through Cloudflare, and two redirect rules send pushdraft.dev/* to draft.shubrt.me/* and <draft-id>.pushdraft.dev/* to <draft-id>.draft.shubrt.me/*, keeping path and query. Shoo issues a different pairwise subject per origin, so the first sign-in on a new origin joins the existing account through Shoo's cross-origin pii_sub, which requires the user's profile consent. Every push to main triggers a Railway deployment to production. The repository has no staging environment or automatic QA pipeline. The preview-domains GitHub Actions workflow provisions and removes preview domains. Pull requests get an ephemeral Railway PR environment with its own Postgres instance and a generated up.railway.app domain. On boot, preview environments seed the account and API-key hash from the PREVIEW_SEED_* variables, so the production CLI key works there and a preview upload uses pushdraft upload ./plan.html --api-url <preview-url> (or the API_URL environment variable). Shoo issues a different pairwise subject per origin, so a preview sign-in matches the seeded account through the stable PREVIEW_SEED_PII_SUBJECT instead of the production subject. Draft content is served only on the per-draft subdomain host, which the generated domain cannot provide, so the preview-domains workflow gives every PR environment its own apex and wildcard domain under preview.pushdraft.dev (Railway custom domains plus DNS-only Cloudflare records, torn down on close; tools/preview-domains.mjs does the work and also runs locally). The PREVIEW_PUBLIC_URL_TEMPLATE variable makes the preview generate its links on that domain, so drafts render in previews exactly as in production.

Packages

• apps/api: Elysia API, Shoo sign-in, PostgreSQL persistence and draft delivery
• apps/cli: pushdraft CLI for authentication, upload, update, list and whoami
• libs/contracts: shared runtime-validated API contracts

CLI

Run the CLI without installing it:

npx pushdraft upload ./plan.html
# or
bunx pushdraft upload ./plan.html

The CLI remembers each file separately for each API URL and account. Switching back to a previous target updates its original draft. Verified key rotation keeps these mappings; unverified keys only reuse mappings for the exact same key. Existing mappings in ~/.pushdraft/drafts.json are preserved on the next upload.

Image uploads accept complete static PNG, JPEG, and static or animated WebP files and keep their original bytes. Animated PNG is not supported; use animated WebP instead. Images are limited to 16,777,216 decoded pixels across all animation frames, as well as the configured upload byte limit. This bounds raw decoding to 64 MiB for RGBA images.

HTML drafts can reference the current version of an image draft by name. For an existing image draft, attach its ID directly:

pushdraft upload ./hero.png
pushdraft upload ./page.html --ref hero=<image-draft-id>

For several local images, prepare a JSON manifest that maps each reference name to an image path:

{
  "hero": "./images/hero.webp",
  "logo": "./images/logo.png",
  "chart": "./images/chart.png"
}

Paths are resolved relative to the manifest. One command uploads the unique images, four at a time, and then uploads the HTML with their draft IDs:

pushdraft upload ./page.html --refs-file ./pushdraft.assets.json

Use the reference names as relative URLs in the HTML:

<img src="refs/hero" alt="Hero" />

Uploading the same local image path again updates its existing image draft. References always serve that image draft's latest version, including when the HTML is opened through a historical page-version URL.

Run npx pushdraft --help for all commands and options.

Share links

The draft detail page can create guest links that expire after 1 hour, 1 day, 7 days or 30 days. A link is pinned to the current draft version and snapshots the current versions of referenced images. It can be revoked at any time, and the recipient does not need a Pushdraft account.

Share links are bearer credentials. Anyone who receives one can open the shared version until the link expires or its owner revokes it.

Agent skills

This repository includes portable skills for agents that support the Agent Skills format:

• pushdraft-write creates and publishes HTML documents with optional local images.
• pushdraft-read reads an existing Pushdraft URL through its raw endpoint.

Install them from the repository with:

npx skills add shubrt/pushdraft

The canonical files live in skills. To install a skill manually, copy its directory to ~/.claude/skills/ for Claude Code or ~/.codex/skills/ for Codex.

Local setup

Requirements: Vite+ (vp), Node 22+, Bun 1.3.10+ and Docker. vp drives installs, scripts, checks and tests; Bun is the API runtime and bundler.

vp i
cp .env.example .env
docker compose up -d postgres
vp run db:deploy
vp run -F @pushdraft/api dev

API start and migration scripts load .env from the repository root. Exported environment variables take precedence, and deployments can run without a .env file.

The apex runs at http://localhost:3003. Drafts use http://<draft-id>.localhost:3003; local DNS support for wildcard localhost names depends on the browser and operating system.

Build the CLI with:

vp run -F pushdraft build
node apps/cli/dist/cli.js auth login --api-url http://localhost:3003

Checks

The browser layout regression checks the draft list, details and CLI setup with long metadata at 320, 375 and 1050 CSS pixels. Install Chromium once, then run it:

vp exec playwright install chromium
vp run test:browser

vp run qa

qa runs formatting, linting, sherif, typechecks and the test suite locally. The preview-domain workflow does not run these checks. Tests live in each package's test/ directory and run from the repository root:

vp test run     # single pass
vp test watch   # watch mode

The start page is public. Access to your draft list and account pages requires a Shoo session. Opening your draft content also uses a one-time subdomain handshake. Valid guest links grant access to the shared version without a Pushdraft account until they expire or are revoked. Agents use a Bearer API key for listing, uploading and fetching their draft files.

License

Pushdraft is available under the MIT License.