init

Scaffold a form YAML from a Google Form URL. Fetches the same metadata as gform inspect and writes step stubs with placeholder answers.

File-upload (and other login-walled) forms need a Google session — anonymous fetch cannot see questions.

basic workflow

gform init 'https://docs.google.com/forms/d/e/…/viewform'
gform init 'https://…/viewform' --name <form>
gform init 'https://…/viewform' -n <form>

# login-walled / file-upload forms:
gform init 'https://…/viewform' -n <form> --auth
gform init 'https://…/viewform' -n <form> --profile work
gform init -n <form> -A -pr work   # same shorts as run

Omit the URL on a TTY to be prompted. Invalid URLs fail before any network call.

Default output: $GFORM_HOME/forms/<name>.yaml (the global library). The form title becomes the name unless you pass --name.

Always review placeholders before run. Init maps public types into YAML steps:

inspect type	scaffold
multiple_choice / linear_scale / rating	radio (+ pool when options exist)
dropdown	select (+ pool)
checkboxes	checkbox
grid (multi-row)	one radio per row (Title — row)
short_text / paragraph / date / time	text (date/time notes in comments)
title	comment only
file_upload	action: file (commented source: tip + accept)
section	# --- + next between pages

You still need real answers (or pools) for a successful submit. After a successful init, the CLI tips you toward edit:

gform edit <form> --ask                          # fill answers interactively
gform edit <form> --editor vim|nano|cursor       # open YAML, then agent handoff prompt
gform verify <form>
gform run <form> --policy demo

where files land

flag	writes to
(default)	$GFORM_HOME/forms/<name>.yaml
--out <path>	explicit file path
--cwd	also writes ./forms/<name>.yaml in the current directory

gform init 'https://…/viewform' -n <form>
gform init 'https://…/viewform' -n <form> --cwd
gform init 'https://…/viewform' -o ./draft.yaml
gform init 'https://…/viewform' -n <form> --cwd --force

Library-only is the usual path — gform run <form> finds it without a project ./forms/ folder. Use --cwd when you want a repo-local copy alongside the library install. See portable.md.

--out bypasses the library entirely; you may still gform add later to install it.

reserved names

These names are blocked — they collide with gform run subcommands:

list · ls · view · v · last

# bad — will error
gform init 'https://…/viewform' -n list

# good
gform init 'https://…/viewform' -n <new-name>

Same rule applies to gform add --save-as, gform restore --save-as, and gform rename.

force overwrite

gform init 'https://…/viewform' -n <form> --force
gform init 'https://…/viewform' -n <form> -f

Without --force, init refuses if the destination file already exists.

typical pipeline

gform init 'https://…/viewform' -n <form>
gform edit <form> --ask
gform verify <form>
gform inspect <form>
gform add <form>              # if you used --out instead of default library
gform run <form> --policy demo

gotchas

• URL must be a public viewform link — login-walled forms need auth setup after scaffold.
• Init does not submit anything; it only writes YAML.
• Re-running init on the same URL overwrites with fresh public metadata (use --force).
• Question text in YAML must stay in sync if the owner renames fields — re-init or edit manually.

related

• add.md — install YAML into the library
• edit.md — fill placeholders
• verify.md — schema check
• inspect.md — live risk flags
• portable.md — library paths and lookup