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 deliveryapps/cli: pushdraft CLI for authentication, upload, update, list and whoamilibs/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.
