Portable paths & form library

Where gform stores data and how form names resolve.

Data home

Default layout lives under $GFORM_HOME (resolved by core). Fresh installs with no env vars use a native default per host — see platform.

$GFORM_HOME/            # or native default (Linux/WSL: ~/.local/share/gform; …)
  auth/
    active.json
    profiles/<name>/storage.json
    profiles/<name>/meta.json
  forms/                 # global library
  artifacts/             # 16-hex runs/batches, index.json, config.yaml
  browsers/              # default.json preference
  cache/                 # content cache (remote / drive)
  state/                 # CLI cache (version check throttle)
  history.jsonl

export GFORM_HOME=/custom/gform
# or
export XDG_DATA_HOME=/custom/xdg   # → $XDG_DATA_HOME/gform

Form lookup

1. Explicit path: gform run ./forms/<form>.yaml
2. Name lookup (gform run <form>), search order (dirs that exist):
   • --forms-dir <dir> / -fd
   • GFORM_FORMS_DIR
   • ./forms/ (cwd) — skipped if missing
   • $GFORM_HOME/forms/

Scaffold

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

Writes $GFORM_HOME/forms/<name>.yaml by default (and ./forms/ with --cwd). Review placeholders before submit.

Repo assets (examples, not runtime library)

Path	Role
forms/_template.yaml	Starter YAML; shipped with the published root package via files[]
profiles/	Unused stub — comments only. Not loaded at runtime. Runtime auth profiles live under $GFORM_HOME/auth/

Real forms belong in $GFORM_HOME/forms/ (or optional cwd ./forms/).

Library commands

gform add ./forms/_template.yaml --save-as <name>
gform rename <form> <new-name>
gform edit <form> --ask
gform verify <form>
gform verify                 # all in global library
gform delete <form>         # preview, then y/N (default N)
gform delete <form> --yes   # skip prompt (required non-TTY / CI)
gform delete all --yes

rename updates the library file and a cwd ./forms/ twin when both exist.
delete only touches $GFORM_HOME/forms/ — never project ./forms/.

Clean (generated only)

gform clean artifacts
gform clean artifacts --yes
gform clean artifacts --older-than 7 --yes
gform clean history
gform clean auth
gform clean all

Forms are not cleaned — use gform delete. See commands/clean.