Agents

Sixty-second playbook for coding agents (and power users) driving gform. Read this once, then operate without guessing.

Public docs: thegform.pages.dev/agents · Schema: schema.ts on GitHub

Mental model (10s)

1. Form YAML = what to fill (steps, pools, unique, variant mode).
2. Run flags / --policy = how this invocation behaves (headed, repeat, concurrency).
3. Artifacts = every run (and most failures) leave a durable id under $GFORM_HOME/artifacts/ — inspect with gform run view <id>.

CLI owns the terminal; core owns fill/inspect. Never invent CAPTCHA bypasses — soft walls pause for a human on headed TTY; hard walls stop with a reason and keep artifacts.

Global output modes (use these first)

Flag	Short	Effect
--json	-j	Machine output where supported; human [gform] logs off
--json-pretty	-jp	Pretty JSON (default on with --json)
--quiet	-q	Hide info/tip/notice; listing primary payload stays
--silent	-s	Hide info/warn; errors remain; listing off
--debug	-d	Opt-in depth: content resolve/fetch/accept, fill, inspect (stderr + run.log). Default TTY stays quieter — auto-decide chatter is debug-only.
--no-live	-nl	Disable live worker panel on run

Agent default: prefer -j when you will parse stdout. Prefer -q when you want human-readable lists without tip spam. Avoid -s unless you only care about exit code + errors.

Listing (gform list, run intro meta, footers) is quiet-safe — quiet still shows the useful table; silent/json hide it.

Golden path (scaffold → edit → run)

gform init 'https://docs.google.com/forms/d/e/…/viewform' -n <form>
gform edit <form> --ask                    # or --editor vim|nano|cursor|code
gform verify <form>
gform verify <form> --check -A             # refresh accept / stub new questions from live form
gform inspect <form> -j                    # risk flags as JSON
gform run <form> --policy demo             # headed watch
gform run <form> -r 5 -C 3                 # batch
gform run list                             # find ids
gform run view <id>                        # answers, submit, paths

After gform edit … --editor … closes, the CLI prints a pasteable agent handoff prompt. Use it: read this page + schema + the form file, ask how pools should vary, then edit.

Form YAML contract (agents edit this)

Piece	Notes
steps[].action	text · radio · checkbox · select · file · next · back · submit · pause · wait
pool / pools	Variants across --repeat
options.variantMode	rotate (default) · random · zip (equal-length persona rows — gform view previews)
options.unique	Skip when named fields already succeeded (batch or history)
options.headed / repeat	Starters only — CLI / --policy win; run intro shows source
file + source.type	local · gdrive (id and/or link) · remote — or assist-only; see file-uploads

Full shape: schema. Zod truth: schema.ts. Edit command: commands/edit.

Ask before assuming rotate vs random vs zip. Zip keeps name[i] with email[i] and errors if pool lengths differ — confirm with gform view before a big -r.

Ask before inventing file uploads — auto (source) vs headed assist; for Drive, whether they have a file id, a share link, or want assist. Do not invent Drive picker automation. For interactive rematch on mime/size/fetch fail: gform run <form> -H -pa (headed + TTY only — never with -j / -s / CI; headless ignores -pa with a warn).

Auth profiles

gform auth create                 # headed Google login → profile
gform auth list -j
gform auth activate <name>
gform run <form> --auth           # active / picker / first
gform run <form> -A -pr work      # explicit profile (implies auth)
gform doctor --auth               # live session probe

Login-walled forms need --auth (or preflight aborts). Collect-email forms warn without auth; --strict hard-fails. Details: auth · commands/auth.

Browsers

gform browsers list -j            # alias: br
gform browsers check
gform browsers default chromium|chrome|msedge|…
gform browsers setup
gform doctor --browser            # launch probe

Host discovery (WSL / Windows / macOS / Linux) feeds Playwright launch targets. Prefer br in scripts. browsers · commands/browsers.

Run inspection & artifacts (failures are gold)

Every run writes an id (16-hex) with manifest.json, config.yaml snapshot, run.log, and screenshots as needed. Failed steps keep screenshots by default — you do not need --trace just to debug a miss.

gform run list --form <form> -j
gform run view <id>               # answers, submit outcome, paths
gform run view <id> -j
gform run last
gform restore <id>                # revive YAML from snapshot

Flag	What you get
(default)	Screenshot failed steps only → screenshots/step-NN-FAILED.png
--trace	Screenshot every step (success + fail) — visual flipbook
--pw-trace	Playwright pw-trace.zip in the run dir — npx playwright show-trace …
--debug / -d	Content resolve/fetch/accept + fill detail; also policy merge, fingerprints, pool picks, inspect flags

status=success only when submit outcome is ok (or there is no submit step). Skipped duplicates still leave a tiny manifest (status: skipped). Full layout: artifacts.

Soft walls vs hard walls

Kind	Behavior
Soft (CAPTCHA, mid-run login, some validation)	Headed + TTY → pause for human; headless → fail (assist-headed-required) — never pauses
Hard (closed form, missing auth on login wall)	Stop with reason; artifacts kept

No CAPTCHA bypass. Ever. limitations.

Policies (run presets — not form variants)

gform policies -j
gform run <form> --policy safe|demo|load|watch

Form YAML owns pools / unique / variantMode. --policy only bundles CLI-ish run flags. policies.

JSON commands agents lean on

Command	Why
gform list -j	Resolvable forms
gform inspect <t> -j	Live risk flags + question types
gform doctor -j	Host health (--auth / --browser probes)
gform auth list -j	Profiles
gform browsers list -j	Launch targets
gform run list -j / run view -j	Artifact digests
gform version -j	Version / update check
gform policies -j	Preset table

Do / don't

Do

• verify before big -r waves; verify --check after the owner changes file types / questions
• inspect -j once when the form URL is new or owners change fields
• Read run view + fail screenshots before rewriting YAML blindly
• Use --headed --keep-open (-ko) when teaching a soft wall
• Stamp pools so --repeat + --skip-duplicates actually vary

Don't

• Set variantMode: zip without equal-length pools — verify/view will fail; ask the user first
• Silence errors with -s and then wonder why debugging is empty
• Treat form options.headed as stronger than --headed / policy (it isn't)
• Bypass challenges or invent selectors outside the YAML contract
• Automate the Google Drive picker — use source.type: gdrive or headed assist

Related

• install · guide · concepts · schema · inspect-verify · file-uploads · commands/run · commands/edit · artifacts · repeat · limitations · roadmap · portable