add

Validate a form YAML and install it into the global library ($GFORM_HOME/forms/). Use this after hand-editing a file, copying a template, or scaffolding with --out.

basic workflow

gform add ./forms/<form>.yaml
gform add <form>.yaml
gform add <form>                    # name lookup (cwd ./forms, then library)

On success, the file lands at $GFORM_HOME/forms/<name>.yaml where <name> comes from the YAML name: field (or --save-as).

gform list
gform run <form>

save as a different name

gform add ./draft.yaml --save-as <name>
gform add ./draft.yaml -a <name>

--save-as sets the library basename and rewrites the name: field inside the YAML.

force overwrite

gform add ./<form>.yaml --force
gform add ./<form>.yaml -f

Without --force, add refuses if a library form with that name already exists.

reserved names

--save-as cannot target run subcommand names:

list · ls · view · v · last

Pick a clear library id for <form> (letters, digits, hyphens).

when to use add vs init

situation	command
starting from a Google Form URL	gform init <url> (writes + validates)
you already have a YAML file	gform add <path>
file is already in the library	just gform run <name> — no add needed
project-local ./forms/ only	optional — gform run ./forms/<form>.yaml works without add

add runs the same Zod validation as gform verify. Fix schema errors before retrying.

lookup override

gform add <form> --forms-dir ./forms

Overrides the forms search root when resolving a source by name.

gotchas

• add copies/validates into the library only — it does not touch cwd ./forms/ unless the source path is there.
• gform delete removes library forms; gform clean never does. See delete.md.
• After add, gform list shows the form with history counts (initially zero).

related

• init.md — scaffold from URL
• verify.md — check without installing
• list.md — browse installed forms
• portable.md — library layout
• delete.md — remove library forms