@htmlbin/cli — working notes

An honest pass at the problem before we declare it solved. What we're trying to enable, the shape of a candidate solution, where it works, where it breaks, and what's still an open call.

the problem

"PR-preview deploys" is a known shape — most modern hosting providers offer some flavor of it. But those are external services with their own data flows, their own billing, and their own ideas about who can see what. For some orgs that's fine. For others — regulated, security-conscious, or just "we already pay for this infra" — it isn't.

The narrow question we're trying to answer: can we get the same end-user experience using only the infrastructure the org already has?

the user journey we'd want to enable

Concretely, what the engineer should experience:

1. Pushes commits to a branch, opens a PR — exactly as they do today.
2. Within a minute, a sticky comment appears on the PR: "🔍 Preview: <url>"
3. Clicks the URL. Browser gets redirected through the org's SSO if not already signed in.
4. Lands on the rendered page. Reviews. Comments on the PR. Approves.
5. Pushes another commit; the URL updates. PR closes; the URL goes away.

Nothing about that journey is new — every modern hosting provider does some version of it. The interesting question is the plumbing underneath, and which pieces we can fit together from what an org already runs.

candidate solution

A CLI that runs once per PR push, inside CI, and publishes an HTML file to a destination the org already controls. SSO gating belongs to that destination — the CLI doesn't authenticate viewers. The viewer's browser talks directly to the destination and the org's IdP; htmlbin.dev is not in the request path.

One CLI, three possible destinations chosen to match three organizational contexts:

• cloud — htmlbin.dev. Public URLs. The default, but irrelevant for the org-private use case.
• gh-pages — the org's GitHub Pages on a private repo with Pages → "Private."
• cloudflare — Cloudflare Pages behind Cloudflare Access. Relevant for orgs without GitHub Enterprise.

Same CLI verb. Same single-file contract. Different destinations for different contexts. "Destination" is the abstract term throughout — call it the hosting provider when context matters.

how it would actually work — the gh-pages path

End-to-end on every PR push:

ENGINEER       GITHUB.COM      CI RUNNER             HOSTING          IdP
   │                  │                    │                    │                  │
   │ git push (PR)    │                    │                    │                  │
   │─────────────────>│                    │                    │                  │
   │                  │ trigger workflow   │                    │                  │
   │                  │───────────────────>│                    │                  │
   │                  │                    │                    │                  │
   │                  │                    │ npm ci && npm run build                 │
   │                  │                    │   → ./dist/index.html (?)             │
   │                  │                    │                    │                  │
   │                  │                    │ htmlbin publish ./dist/index.html --to gh-pages
   │                  │ Git Data API       │                    │                  │
   │                  │ atomic commit ←────│                    │                  │
   │                  │ to gh-pages/pr-N/  │                    │                  │
   │                  │                    │                    │                  │
   │                  │ Pages rebuild ──────────────────────────>│                  │
   │                  │                    │                    │                  │
   │                  │ sticky comment     │                    │                  │
   │                  │<───────────────────│                    │                  │
   │                  │                    │                    │                  │
   │ click URL        │                    │                    │                  │
   │──────────────────────────────────────────────────────────>│                  │
   │                                                            │ 302 → SSO ─────>│
   │ sign in ───────────────────────────────────────────────────────────────────>│
   │<─────────── session cookie ──────────────────────────────────────────────────│
   │ retry ────────────────────────────────────────────────────>│                  │
   │<───────────── 200 OK, HTML ───────────────────────────────│                  │

Three real commands run in the runner. No magic:

- run: |
    npm ci
    npm run build               # produces HTML — IF the repo's build does that
    npx @htmlbin/cli publish ./dist/index.html --to gh-pages
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

where it works cleanly — and where it doesn't

Three concrete user journeys map onto today's reality. One is the original problem; the other two are the rest of the world.

the generation problem

For non-static repos, "the preview" doesn't pre-exist anywhere. Something has to look at the PR's changes and produce HTML that represents them. The CLI's contract is publish-only, so generation needs to land upstream of the publish step — and the generator has to be more than a single API call. The thing that makes today's coding agents useful is the harness: file access, shell execution, multi-turn refinement, validation. A raw model call against a diff gives you noise; an agent loop gives you a real artifact.

We are not going to build a generation engine. The agent-harness pattern is well-established across the coding-tools landscape; multiple existing systems already do PR-aware code work with real tool use — file system access, bash execution, multi-turn refinement. The pragmatic move is to leverage one of them.

Decision: Option 1. The agent runs in the CI runner; htmlbin-cli stays publish-only and consumes whatever file the agent writes. The other two options stay as alternatives we might revisit, but neither ships now.

the risks we know about

what we're deliberately not solving

what's actually in tree

v1 of the CLI lives on a working branch. Concrete state:

CLI ergonomics — with attribution

The patterns that make a CLI feel native to coding agents aren't ours to invent. DataDog's pup CLI and its public design notes — along with the Speakeasy team's writeup on engineering an agent-friendly CLI — lay this out clearly enough that the right move is to copy what works. A few conventions we adopted directly:

• Auto-detect the runner. When a known coding-agent env signature is present (Claude Code, Cursor, Codex, Aider, Cline, and several others), the CLI defaults to machine-readable output. The agent doesn't have to know about the flag. A manual override covers runners we haven't named.
• One error shape, end to end. The CLI's machine errors mirror the API's error.code contract — same keys agents already parse on the wire. No second vocabulary to document.
• Richer User-Agent. Every outbound call carries CLI version, runtime version, OS / architecture, and the detected agent name — visible to operators server-side without changing the API shape.
• Stable, categorized exit codes — already in tree; pup's doc validated that the categories we picked (auth, not-found, rate-limit, size, input, network) are the conventional ones.

Three pup patterns we deliberately didn't take, with reasons:

• OS-keychain token storage. Conflicts with the file-based storage the agent protocol descriptor at /api/onboard advertises, and agents typically can't reach the keychain. Revisit if humans complain about plaintext-at-rest.
• List response envelope (count / truncation / warnings around a data field). Breaking shape change to our current JSON array — worth doing alongside real pagination, not standalone.
• Verbose API tracing flag. Useful once we're running the non-cloud destinations end-to-end against sandboxes. Not now.

Credit where due: github.com/DataDog/pup and Speakeasy's engineering-agent-friendly-cli post. Both are good reads for anyone shipping a CLI that agents will use.

open questions

1. What does "good preview HTML for a PR" actually look like? Until we try it on a real PR with the Option 1 workflow, we're guessing. The prompt in the reference workflow is a starting point; teams will tune it for their change types. The empirical answer drives whether Option 3 (htmlbin owning a prompt) ever makes sense.
2. Which agent CLI do we lead the reference workflow with? Claude Code -p is the chosen example because the syntax is the most concise. Codex CLI codex exec is documented as a swap-point. We're not endorsing one over the other.
3. Is the Octokit git.getRef URL-encoding a real bug? A 30-minute test against a real private repo answers it.
4. Does the three-token UX hold up? Or do we eventually need a per-destination htmlbin login with a unified config?
5. Is "three destinations" the right framing, or does it dilute the product? Cloud + one alt might be cleaner than cloud + two alts that overlap.

what to learn next

Two experiments answer most of what's still uncertain:

1. End-to-end gh-pages flow against a real private repo + GH Enterprise Cloud. Confirm SSO redirect works, the Octokit URL encoding isn't actually broken, and the rebuild lag is tolerable.
2. Run the Option 1 reference workflow on a real non-static repo PR. Use the shipped agent-preview-workflow.yml, swap in an Anthropic API key (or Codex equivalent), and see what HTML the agent actually produces. Iterate on the prompt; record what kinds of PRs the pattern handles well vs. where it produces noise. That data tells us whether Option 3 (sugar layer) is worth building later, and whether to ship a curated set of prompts for common change types.

The code in tree can stay either way. Those two experiments tell us whether to keep building, change scope, or pick a different direction entirely.