F Frontpage
Get started
Developers Agent runs

Developers

Agent runs

Start Frontpage editor agent runs from the CLI, wait for completion, cancel or retry, and keep file sync from colliding.

What an agent run is

frontpage prompt enqueues the same gated editor agent pipeline as Prompt in the app. Frontpage applies AI edits on the site branch and builds staging at https://<subdomain>.frontpage.host.

Runs update staging only. Never follow a successful run with frontpage publish unless the user explicitly asked.

Start a run

frontpage prompt "Make the hero shorter and increase contrast on the CTA"
frontpage prompt "Add a pricing FAQ below the fold" --path /
frontpage prompt "Use this logo in the header" --attach ./logo.png
frontpage prompt "Match this brand PDF" --attach ./guide.pdf --path /
frontpage prompt "Reuse uploaded art" --attach /__media/uploads/<slug>/<file>
frontpage prompt "…" --asset-url "https://….blob.vercel-storage.com/uploads/…"
frontpage prompt "…" --json
# JSON includes data.runId (+ data.attached counts); without --json, stdout is the bare runId

Optional --path must start with / (page scope hint). Be specific: which page, which section, brand constraints, and what not to change.

--attach accepts a local file (uploads via the same path as frontpage media upload), an existing /__media/… site path, or an https:// Blob URL. Repeatable. --asset-url adds a legacy https image URL. Caps match media proxy uploads (images / PDF / text); CLI video and oversized binaries are not supported yet.

List, inspect, wait

frontpage runs
frontpage runs list --json
frontpage runs current --json
frontpage runs get <runId> --json
frontpage runs wait
frontpage runs wait <runId> --json

Without an id, runs wait targets the active or latest relevant run for the linked site. Prefer waiting before you review the subdomain or attempt another push. Failed or canceled waits exit 2; with --json the envelope is ok: false and includes data.run (with run.error when present).

Cancel and retry

frontpage runs cancel <runId>
frontpage runs retry <runId>

Only cancel when the user asked, or when a stuck run is blocking required push work and your policy allows it. Mid-task continuation is automatic — there is no runs continue in v1.

Optional build wait

frontpage deploy wait --json

Blocks until no run is queued/running/deploying. Fail-closed: exit 2 when the waited run (or the latest run, if already idle) is failed or canceled. This is not publish and not a separate “deploy to staging” step. Staging is already the subdomain once the build finishes. API errors include a requestId in --json error envelopes.

Click-edit (different path)

Exact single-occurrence text replace uses edit, not prompt: 

frontpage edit --path / --old "exact old string" --new "exact new string"

Fails if the old string matches zero or 2+ times. Updates staging via the click-edit path (not file push / gated-write). See Content & settings.

Conflict with file sync

While a run is active, push and revert refuse with conflict (exit 3). Wait or cancel, then retry.

Related commands

  • frontpage pages --json — list site pages
  • frontpage usage — plan and AI/bandwidth usage
  • frontpage analytics [--days 7] — analytics JSON

Also see