F Frontpage
Get started
Developers File sync

Developers

File sync

Pull and push allowlisted Frontpage site files with compare-and-swap, active-run guards, and staging previews.

Allowlist

Only these roots sync:

  • src/
  • public/
  • content/

Paths outside those roots never pull or push. Some scaffold files are platform-owned and refuse CLI read/write even under src/ (example: certain layout shells).

Pull (and when to pull)

frontpage pull
frontpage pull --site acme --json

Writes files into the current working directory and updates .frontpage/state.json with slug and baseCommitSha.

Pull before editing when the remote tip may have moved (UI agent, another machine, or a prior push elsewhere). Check frontpage status --json or frontpage diff --json for tipDrift. Compare-and-swap only blocks a stale push — it does not stop you from editing a stale local tree. The UI/canvas agent does not use this CLI; it edits the live tip in-process.

Inspect remote

frontpage ls
frontpage ls src/pages
frontpage cat src/config/site.ts
frontpage search "hero" src/
frontpage search "data-fp-form" --files-only
frontpage search "font-sans" src/ --case-sensitive --max-results 20
frontpage status --json
# data.tipDrift === true → run pull before editing further

Diff local vs remote

frontpage diff
frontpage diff --json
# data.dirty, data.tipDrift, data.comparedWith === "blobSha"
# data.added, data.modified, data.deleted

Diff compares git blob SHAs from one file-list request — it does not download every remote file. Markers in human mode: A local-only, M modified, D remote-only. When tipDrift is true, pull before more edits even if dirty is false.

Push

frontpage push --message "Update pricing FAQ copy"
frontpage push --site acme --message "…" --json
frontpage push --message "…" --wait
# --wait blocks until no agent run is queued/running/deploying (same as deploy wait)

Requirements:

  1. baseCommitSha present (run pull first)
  2. At least one allowlisted file in the folder
  3. No active agent run (otherwise exit 3)
  4. Remote tip still matches your base (CAS); otherwise exit 3

Push updates staging (https://<subdomain>.frontpage.host). It does not publish production. Review the subdomain after the build.

CAS recovery

# exit 3 from push
frontpage status --json
frontpage pull
# re-apply your edits if needed
frontpage push --message "…"

Active-run guard

While an editor agent run is queued/running/deploying, push and revert refuse with conflict (exit 3). Wait with frontpage runs wait or cancel if appropriate.

Side effects to know

  • Pushing module markup may auto-activate modules (same as the editor agent).
  • tokens.ts may be auto-repaired at commit if it would break the build.
  • Binary files use base64; do not UTF-8 round-trip them.

Full-tree semantics

For allowlisted roots, the local tree you push is the intended remote tree for those roots. Deleting a local allowlisted file and pushing removes it remotely (subject to guards). Keep your working tree intentional.