run

Execute a form against the live Google Form page. This is the main operator command — everything else (init, edit, verify) exists to get you here safely.

basic run

gform run <form>
gform run ./forms/<form>.yaml
gform run <form> --policy demo
gform run <form> --headed

Default is headless (no window). Pass --headed (or --policy demo|watch) to watch. Form YAML options.headed / options.repeat are starters: they apply only when CLI / named --policy did not set them. Run intro shows the source (form.yaml vs --headed vs policy demo). If the GUI cannot open, gform warns and falls back to headless instead of dying.

Headed runs prefer gform browsers default (e.g. Linux Chrome on WSL) — same as auth create. Playwright’s bundled Chromium often reports “headed” with no visible window on WSLg (playwright cr hangs the same way); set gform browsers default chrome if the window still doesn’t appear.

<form> resolves by name (cwd ./forms/ then library) or as an explicit YAML path. See portable.md for lookup order.

Preflight inspect runs automatically unless you pass --skip-inspect. See inspect.md for risk flags.

live panel vs print-and-go

On a TTY, gform run shows a live worker panel — one line per parallel worker updating in place. Good for watching repeat batches.

gform run <form> -r 10 -C 3          # live panel (default on TTY)
gform run <form> -r 10 -C 3 -nl       # print-and-go logs
gform run <form> -r 10 -C 3 --no-live

Use -nl / --no-live when piping logs, in CI, or when the panel fights your terminal multiplexer. Non-TTY environments skip the panel automatically.

repeat, concurrency, pools

gform run <form> -r 10 -C 5 --delay 2s
gform run <form> -r 10 -C 3 --skip-duplicates
gform run <form> -r 10 --variant-mode random

flag	purpose
-r / --repeat <n>	run N times (batch)
-C / --concurrency <n>	parallel workers (max 16)
-D / --delay <duration>	pause between sequential runs only (-C 1; ignored with parallel workers) — 500ms, 2s, 1m; bare number = seconds
--once	skip if this exact fingerprint already succeeded
--skip-duplicates	skip fingerprints that already succeeded in history
--continue-on-error	keep going after a failed repeat
--variant-mode rotate|random|zip	how step pool: values are picked

Concurrency clamp: if -C exceeds the worker max (16) or -r, gform warns and caps workers — extra slots would sit idle. Example: -r 20 -C 20 → warn, use 16. Live panel rows still respect global -T (default 10) / -F.

Pools matter for repeats: without pool: on steps, every repeat resolves the same answers. --skip-duplicates then skips almost everything. Add pools in YAML (or via gform edit --ask) so each run gets a distinct fingerprint. See repeat.md.

auth and login walls

gform run <form> --auth
gform run <form> --profile work
gform run <form> -A -pr work

--profile implies --auth. Resolution order: explicit --profile → active profile → TTY picker → first profile (non-TTY).

Login-wall forms need --auth or they abort at preflight. See auth.md for creating profiles.

unique fields and skip-duplicates

YAML options.unique and CLI --skip-duplicates / --once are different gates:

gate	what it blocks
unique.scope: batch	same field values within this --repeat wave only
unique.scope: history	same field values across past successful solo runs and children inside finished batches + this batch
--skip-duplicates / -sd	whole-payload fingerprint already succeeded (history or this batch)
--once	base fingerprint already succeeded — skip the whole invocation

gform run prints a notice when any of these are active, and a warn with the reason when a run is skipped. scope=batch on a single gform run (no -r) never collides with yesterday's runs — use history or -sd for that.

soft walls and assist

Assist only when headed and on a TTY. Headless never pauses for Enter — there is no window to fix.

On a headed TTY, soft walls (captcha, login prompt mid-run, Drive file UI, fill misses) pause — solve in the window, press Enter, continue.

gform run <form> -H                   # watch + assist on TTY (--headed)
gform run <form> -H -ko               # leave window open after (handy for uploads)
gform run <form> -H --no-assist       # fail fast on soft walls (CI)
gform run <form> -H -pa               # ask at file / login / browser / soft-wall forks
gform run <form>                      # headless: soft walls / assist-only files fail with tip

-pa / --prefer-ask needs headed mode and an interactive TTY. Headless (no --headed / -H and no headed policy) → warn and ignore -pa for that run. Non-TTY, CI, --json, or --silent → warn and refuse before any form load / browser work. Esc cancels the menu and stops the run.

-ko / --keep-open likewise needs headed mode; headless → warn and ignore.

Under -pa, mime / size / fetch fails on file steps open a rematch menu (local path, Drive id|link, remote url, raise maxBytes, assist, skip, abort). Login walls and headed-GUI launch failures ask before enabling assist or falling back to headless.

file steps: set source.type to local | gdrive | remote for auto-upload when the DOM allows (bytes land in artifacts/<id>/content/); omit for assist-only (needs --headed). gdrive accepts id: and/or link: (link is parsed to an id). Drive / in-browser picks without YAML source are detected as assisted — local bytes when the session can fetch the chip. After assist, content status is honest: uploaded / assisted / skipped. Headless assist need → reason assist-headed-required. If you submit the form yourself during a pause → assist-advanced (run stops).

Deep dig + decide-log map: file-uploads.

With --keep-open / -ko, after a successful run the browser stays open for inspection. Close the window, or press Ctrl+C / Ctrl+Z — that exits cleanly (run · ok), not as Interrupted (SIGINT) / fail.

Headless / non-TTY: soft walls fail with a clear tip. Use --policy demo or watch for headed debugging. Full semantics: limitations.md.

--strict aborts early when invisible captcha is detected (used by safe policy).

policies

Named presets bundle common flag combinations. See policies.md.

gform run <form> --policy safe
gform run <form> --policy load
gform run <form> --policy demo --headed   # demo already headed; explicit is fine

browse past runs

gform run list
gform run list --form <form>
gform run view             # TTY: pick an artifact
gform run view <id>
gform run last
gform run delete           # TTY: pick an artifact
gform run delete <id>
gform run rm <id> --yes    # alias; skip confirm
gform run rm <id> --force  # override live/stale-running protect

run list labels top-level entries as single (one run) or batch (a --repeat wave). JSON still uses internal kind: "run" | "batch". A content chip appears when the artifact has an uploaded content/ dir.

List/view also print a frozen reason (colored) and message (dim) when present. Batches show rollup counts; a batch reason appears only when all children share one reason code.

run view prints a compact Config block (unique / tags / variant when present) and a Content section for file step artifacts (artifacts/<id>/content/ + manifest.content[]). config.yaml remains the form snapshot.

delete one artifact

Removes the artifact directory, refreshes artifacts/index.json, and drops matching rows from history.jsonl.

Important: after run delete / run rm, unique / --once / --skip-duplicates can no longer see that run — the history ledger for it is gone. Use this when you mean to forget a run locally; use gform clean artifacts for bulk wipe.

If the artifact looks live (running + recent writes), delete refuses and asks you to wait. Stale-running needs --force. Prefer finishing the other terminal’s job over force-deleting.

Batch children (id/r01) cannot be deleted alone — delete the parent batch id (removes the whole wave).

Top-level gform delete / gform rm removes library form YAML only — not artifacts. See delete.md.

other useful flags

flag	purpose
--headed / -H	show browser window (default is headless)
--keep-open / -ko	leave browser open after finish (headed; headless warns + ignores)
-pa / --prefer-ask	ask at file rematch / login / browser / soft-wall forks (headed + TTY; headless warns + ignores)
--trace	screenshot every step (default: failures only)
--pw-trace	Playwright trace.zip in the artifact dir
--skip-inspect	skip preflight metadata inspect
-d / --debug	opt-in content resolve/fetch/accept + fill detail (stderr + run.log); without -d, auto-decide chatter stays quiet

gotchas

• Reserved form names: list, ls, view, v, last, delete, rm — cannot be library form names.
• Headed: --headed / -H, headed --policy, or form YAML options.headed starter (CLI/policy win). Intro shows the source.
• Soft-wall assist needs a real window — headless never pauses (effective assist off).

related

• inspect · inspect & verify · auth · policies · repeat · file uploads · artifacts · limitations · concepts