Flags & machine I/O

Global flags

These are stripped by the CLI before a command sees the rest of the argv. You can put them before or after the verb. Command-specific flags are documented on each guide (People, Content, File sync). Unknown leftover flags fail closed on commands that check (exit 2).

Flag	Value	Effect
--json	boolean, no value	Stable JSON envelope on stdout for supported commands. Failures still set the process exit code. Parse ok and error.exitCode. Do not scrape human text
--quiet	boolean, no value	Suppress progress spinners and chatter. Errors still print
--site / -s / --site=<slug>	subdomain slug	Override which site this command talks to. See below. Most site-scoped commands accept it
--yes	boolean, no value	Confirm destructive ops when there is no TTY: unpublish and revert only. Other commands ignore it
--help / -h	boolean	Per-command help (same as frontpage help <cmd>)
--message "…"	string	Commit message for push. Required by that command, not global for others
--limit <n> / --page <n>	positive integer	History pagination where that command supports it
--wait	boolean	push / publish: block until the compile (or publish) is ready

What --site means

Frontpage sites are addressed by a subdomain slug. That is the label that appears as https://<slug>.frontpage.host. It is the value in the subdomain column from frontpage sites --json. It is not a custom domain, not a full URL, not a Git branch, and not a site UUID.

# These all mean the same site, "acme"
frontpage people list --site acme
frontpage people list -s acme
frontpage people list --site=acme
frontpage use acme && frontpage people list
frontpage shop items list --site acme

Resolution order

1. --site / -s / --site= on this command. Wins for this process only. Does not rewrite .frontpage/state.json.
2. slug inside .frontpage/state.json in the current working directory (written by frontpage use <slug>).
3. Error (exit 2) if the command is site-scoped and neither is set: No site selected. Run: frontpage use <subdomain> or pass --site <subdomain>.

frontpage use also clears baseCommitSha. Run pull again before push after switching slugs in a folder.

Slug rules (accepted vs rejected)

The CLI lowercases and trims the value, then checks it locally before any HTTP call. The API repeats the same check.

You type	Result
acme, asimov-press, landing	Accepted (if you are a member; otherwise the API still returns 404)
Acme	Accepted as acme
acme.frontpage.host	Rejected locally. Contains .
https://acme.frontpage.host	Rejected. Contains : / / / .
www.example.com or a custom domain	Rejected. Custom domains are display metadata, not CLI targets
A site UUID	Rejected if it contains characters outside the slug pattern. Never use UUIDs as --site

Pattern: ^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$. Letters, digits, hyphens. Must start and end with a letter or digit. No dots, slashes, or colons. DNS label max is 63 characters. New sites also have a 6-character minimum at claim time. Existing short slugs (if any) still work as targets if they match the pattern.

A syntactically valid slug you do not belong to is not a local error. The API returns 404 Site not found. so callers cannot enumerate tenants. CLI exit 4. See Isolation & keys.

JSON envelope

{
  "ok": true,
  "command": "status",
  "data": { }
}

{
  "ok": false,
  "command": "push",
  "error": {
    "message": "…",
    "code": "conflict",
    "httpStatus": 409,
    "exitCode": 3
  }
}

Failures with --json still use the process exit code; the envelope is on stdout. Some content commands already return JSON bodies even without the flag (for example seo get, inbox without --csv). You can still wrap with global --json where supported.

Environment overrides

These are the only process environment variables the CLI reads for API access. Do not invent others.

Variable	Required	Purpose
FRONTPAGE_API_KEY	no (keychain / login file is the default)	Bearer key for this process. Always wins over the OS keychain and ~/.config/frontpage/api-key. Use in CI. Value starts with fp_live_
FRONTPAGE_API_BASE	no	API origin. Default https://app.frontpage.host. Only change this if an operator told you to point at another Frontpage API host

TTY vs CI

• Interactive prompts require a TTY unless you pass the value / --yes.
• In CI, set FRONTPAGE_API_KEY and prefer --json.
• People, inbox, and other PII commands should not print raw payloads into public CI logs. Redirect or use --json into a private file.