Auth profiles

Optional Google sessions for login-walled forms, collect-email, and Drive file fetches.

Related: commands/auth · browsers · doctor · file-uploads

Never commit storage.json, cookies, or real account addresses. Examples below use placeholders.

Storage

$GFORM_HOME/auth/
  active.json
  profiles/<name>/storage.json
  profiles/<name>/meta.json

Create and use

gform auth create work          # sign in (prefers system Chrome)
gform auth activate work        # set active (first profile auto-activates)
gform auth list                 # auth ls
gform auth view work            # auth v
gform auth verify               # auth ver — live classify sessions
gform auth delete work          # auth rm

gform run <form> --auth        # -A — active / picker / first
gform run <form> --profile work  # -pr — implies auth

Aliases: cre · act · ls · v · rm · ver.

Resolving --auth on run

1. --profile <name> if set
2. else active profile (active.json)
3. else TTY → interactive picker
4. else non-TTY → first profile

No --auth / --profile → no session loaded, even if profiles exist.

Google “This browser or app may not be secure”

Playwright’s bundled Chromium is branded Chrome for Testing. Google often rejects sign-in there.

gform auth create opens one Playwright-controlled window:

1. --open <id> if set
2. else gform browsers default
3. else auto: Chrome → Brave → Edge → Chromium → Playwright

Optional --default-browser also opens the OS default browser as a reference — cookies do not transfer; finish sign-in in the gform window.

Create / verify semantics

• auth create only saves after a real Google sign-in (myaccount + auth cookies). Enter on the login page alone is rejected.
• Account email is stored when readable; the same Google account under a second profile name is blocked.
• auth verify / doctor --auth:

Outcome	Meaning
ok	Signed in; refreshes lastVerifiedAt / email in meta
invalid	Confirmed signed out; meta → invalid
inconclusive	Network / timeout / launch failure — not treated as logout

Saved meta (what doctor shows by default) can lag until you live-verify.

Security

• Profiles are local secrets — treat like cookies
• Do not commit $GFORM_HOME/auth/ or copy storage.json into the repo
• gform clean auth removes all profiles (confirm on TTY; --yes for CI)
• Prefer least-privilege Google accounts on forms you own

WSL / browsers

Prefer Linux Chrome for create/verify. Windows .exe under /mnt/c is often found but not controllable. See browsers.