Guide

Day-to-day path: install → scaffold → edit → inspect → verify → run → read artifacts.

Also: install · concepts · commands

Install (short)

pnpm add -g gform
pnpm exec playwright install chromium

From the repo: pnpm install && pnpm build && pnpm i -g . — full detail in install.

Data: ~/.local/share/gform/ (override with GFORM_HOME).

First form lifecycle

gform init 'https://docs.google.com/forms/d/e/…/viewform' -n <form>
gform edit <form> --ask
gform inspect <form>
gform verify <form>
gform verify <form> --check          # optional: sync safe fields from live form
gform run <form> --policy demo       # headed watch + soft-wall assist on TTY
gform run last

Step	What you get
init	YAML scaffold from live public metadata (placeholders to review)
edit --ask	Interactive REPL for steps, pools, options
inspect	Risk flags: login, captcha, file upload, closed, …
verify	Zod schema check against the local contract
verify --check	Re-inspect live form; propose accept / stub updates
run	Submit (or batch); write artifacts under $GFORM_HOME/artifacts/
run last / run view	Answers, submit outcome, paths, reasons

File-upload forms often need auth on inspect/init/check:

gform init '<url>' -n <form> --auth
gform verify <form> --check --auth
gform run <form> --auth --policy demo

Reading the first artifact

After a run:

id  a3f9c1e2b4d60718
→   gform run view a3f9c1e2b4d60718

gform run last
gform run list
gform run view <id>

Expect: resolved Answers, Submit outcome, optional Content for file steps, config.yaml snapshot, fail screenshots by default. Deep dive: artifacts.

Commands at a glance

Command	Alias	Purpose
gform list	ls	Resolvable forms
gform view	v	Resolved form config
gform init <url>	—	Scaffold YAML
gform add <source>	—	Install into library
gform rename	ren	Rename library form
gform edit	—	Editor / --ask
gform verify	ver	Schema (+ optional --check)
gform inspect	insp	Live metadata / risks
gform run	—	Execute / browse artifacts
gform restore	rs	Restore YAML from artifact
gform auth …	cre/act/ls/v/rm/ver	Sessions
gform browsers …	br + ls/chk/def/set	Launch browsers
gform doctor	—	Host health
gform policies	pol	Named presets
gform delete	rm	Remove library forms
gform clean …	art/hist	Purge generated data
gform version	-V	Version / update check

Full reference: commands/. Global flags and alias notes: commands/help.

<form> is a library name or a path (./forms/<form>.yaml). Lookup order: portable.

Edit

gform edit <form>                  # $EDITOR, else detected IDE
gform edit <form> --editor cursor
gform edit <form> --ask            # interactive config REPL (-ak)
gform edit <form> --ask --editor code
gform edit <form> --print          # resolved path only

edit --ask REPL

Ctrl+C / Ctrl+Z cancel the session once. Esc = back a level. Prefer Quit for a clean footer.

Main
  Preview changes / Save
  Form meta (name, url)
  Options (headed, repeat starters, timeouts, variantMode, unique, …)
  Steps (edit / insert / delete / reorder / pools)
  Open in $EDITOR
  Quit

File steps: source.type local | gdrive | remote, or leave empty for headed assist. Map: file-uploads. YAML contract: schema.

Common recovery

Symptom	Try
Soft wall (CAPTCHA / login / validation)	--headed (or --policy demo) on a TTY; finish in browser, press Enter
Login-walled form	gform auth create → gform run … --auth
Google rejects Playwright Chromium sign-in	gform auth create work --open chrome — auth
Schema / unknown key	gform verify <form>; fix YAML
Live form drifted	gform verify <form> --check (add --auth for file forms)
Failed run	gform run last / gform run view <id> — screenshots, reason, run.log
Host / browser confusion	gform doctor --browser · gform br list
Need YAML from an old run	gform restore <id>

Unattended checklist

• [ ] All pages answered in YAML; last step is submit (not pause)
• [ ] gform verify clean; pools if you use --repeat + dedupe
• [ ] Headless default or --policy load / safe
• [ ] Soft walls: either none expected, or --no-assist and accept hard fails
• [ ] Auth only when needed: auth create → --auth / --profile
• [ ] You own or are authorized to submit to the form

Next

• Concepts — mental model
• Inspect & verify
• Run · Repeat
• Limitations · Roadmap