F Frontpage
Get started
Developers Agent quickstart

Developers

Agent quickstart

How coding agents should use the Frontpage CLI safely: staging on the subdomain, no autonomous publish, and a paste-ready brief.

Paste-ready brief

Copy this into Claude Code, Cursor, Grok Build, or any coding agent. The same text is available in the editor under profile → Developers. 

Use the Frontpage CLI to work on my site. Install npm package frontpage-host (binary: frontpage; do not install the unrelated package named frontpage). Login with my API key, then frontpage sites and frontpage use <subdomain>. Read AGENTS.md from the package and run frontpage help site-building (Astro contract: pages map, BaseLayout, tokens, no backends/fake forms). Use frontpage fonts to pick installed font values and frontpage tokens set for surgical token edits; frontpage modules docs / extensions docs for how-tos. At session start (and whenever tipDrift may be true), frontpage pull — then edit under src/, public/, or content/, frontpage diff --json, then push. Prefer --json. Staging is https://<subdomain>.frontpage.host — push/prompt/edit update staging; there is no separate staging deploy step. Never run frontpage publish or unpublish unless I explicitly ask (or a workflow I defined requires it). Do not unpublish or revert unless I ask. After changes, have me review the subdomain before production.

What good agent behavior looks like

  1. Install frontpage-host and authenticate non-interactively.
  2. Resolve the site with frontpage sites --json and use <subdomain>.
  3. Read AGENTS.md and frontpage help site-building (or Site building on the docs site).
  4. Pull (session start / when tipDrift) → edit allowlisted files → diff --json → push with a clear message.
  5. Point the human at https://<subdomain>.frontpage.host for review.
  6. Stop. Do not publish unless asked.

Using the in-product agent vs the CLI

Path Command Notes
Editor-style build frontpage prompt "…" [--attach …] Enqueues the same gated agent pipeline as the toolbar. Prints a runId. Attach images/PDFs/video/text with --attach (local file via media upload caps, /__media/…, or https Blob URL).
Wait for completion frontpage runs wait [runId] Poll until succeeded / failed / canceled. Mid-task continuation is automatic (no runs continue).
Local file editing pull / edit / push Best for coding agents with a working tree. CAS-protected.
Exact text swap frontpage edit --path / --old "…" --new "…" Click-edit semantics (single occurrence). Updates staging.

Example: local edit loop with JSON

export FRONTPAGE_API_KEY=fp_live_…
cd ~/work/my-site
frontpage use acme
frontpage pull
# …edit src/pages/index.astro…
frontpage diff --json
# data.dirty / data.tipDrift; comparedWith === "blobSha"
frontpage push --message "Tighten hero copy on the homepage" --json
# tell the user to review https://acme.frontpage.host
# do NOT run: frontpage publish

Example: prompt the Frontpage agent

frontpage prompt "Make the hero shorter and increase contrast on the CTA" --json
frontpage prompt "Use this logo in the header" --attach ./logo.png --json
# data.runId; data.attached when files were attached
frontpage runs wait --json
# review https://<subdomain>.frontpage.host

Hard no’s for agents

  • frontpage publish / unpublish without an explicit user request
  • frontpage revert without an explicit user request
  • Inventing commands: domains, billing, members, runs continue, MCP, git remotes
  • Using a custom domain as --site
  • Editing files outside src/, public/, content/ and expecting them to sync
  • Treating deploy wait as “ship to production”

Ship the package docs with the agent

After npm i -g frontpage-host, open the files next to the package (or from the npm tarball):

  • AGENTS.md — full operating manual
  • llms.txt — compressed pointer file
  • README.md — human landing page

Recovery cheat sheet

Symptom Next step
Push exit 3 status --json → pull or runs wait → retry push
Exit 4 / mysterious 404 Verify key, membership, and subdomain slug (not FQDN)
Exit 2 Check rate limits vs frontpage usage plan meters
Unsure what commands exist frontpage help --json — do not invent APIs

Canonical introspection

frontpage help --json
frontpage help sync
frontpage help agent
frontpage help content
frontpage help exit-codes
frontpage doctor --json

Also see