gh-postplan

Publish one HTML draft to GitHub Pages and get a stable, shareable URL. Every changed publish also keeps a permanent version URL.

Requirements

• Authenticated GitHub CLI
• Git
• Bun, or Node.js 22.18+

Setup

Configure an existing repository:

npx gh-postplan setup owner/pages-repo

Or create a new public repository:

npx gh-postplan setup owner/pages-repo --create

Setup creates or reuses the gh-pages branch, adds .nojekyll, and configures branch-based GitHub Pages. GitHub Pages is public even when an existing source repository is private.

Publish

npx gh-postplan publish ./draft.html

The command prints progress to stderr and only the stable URL to stdout. Publishing the same file again updates that URL and creates a permanent version such as /drafts/a1b2c3/v2/. Unchanged HTML creates no version.

# Make a separate draft from the same file
npx gh-postplan publish ./draft.html --new

# Reconnect a file after losing local state
npx gh-postplan publish ./draft.html --draft a1b2c3

# Return immediately after pushing
npx gh-postplan publish ./draft.html --no-wait

Only the HTML file is uploaded. Use self-contained HTML or absolute URLs for assets.

List and delete

npx gh-postplan list
npx gh-postplan delete

Both commands read the local cache, so the draft list appears immediately. Drafts are shown by their HTML <title>. In delete, use the arrow keys to move, Space to select multiple drafts, and Enter to delete them. Deleting a draft removes its stable URL and every permanent version.

Configuration lives in ~/.config/gh-postplan. Set GH_POSTPLAN_REPO=owner/repo to override the configured repository.

The npm package also includes an agent skill at skills/gh-postplan/SKILL.md.