Frontpage
Sign Up
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 "…" --attach "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. Attachments use the same upload limits as frontpage media upload.

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.

Site compile wait

frontpage deploy wait --json

First waits for any in-flight editor agent run (fail-closed on failed/canceled). Then polls GET /api/v1/sites/<slug>/deploy until ready. The live compile SHA equals the git tip. A file-only push has no agent run; this command still waits for the compile. Exit 2 on compile failure or timeout. This is not publish.

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

Models and AI credits

GPT 6 Luna is the platform default for new website runs. A site with an explicit model preference keeps that choice; a run already in progress keeps its selected model. In Site preferences, choose Follow platform default to use the current default.

Website runs and AI Support Agent use your site's shared AI credit allowance. Usage depends on the selected model and the work performed. You can review AI usage in the workspace's Usage & plan page.

Retrying delivery of the same usage receipt does not charge twice. A separate paid model attempt has its own usage receipt.

Also see