auth (command)

CLI commands for Google session profiles. Profiles store Playwright cookies so gform run --auth can fill login-walled forms.

For the full session story (storage layout, verify semantics, duplicate detection), see auth.md.

create a profile

gform auth create
gform auth cre work
gform auth create work --url 'https://accounts.google.com'
gform auth cre work -u 'https://accounts.google.com'
gform auth create work --open chrome
gform auth cre work -o chrome
gform auth create work --default-browser

Opens a Playwright-controlled browser window. Sign in with Google; gform saves cookies only after a real session is detected.

Browser pick order: --open <id> → gform browsers default → auto-discovery. See browsers.md.

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

activate

gform auth activate work
gform auth act work
gform auth activate                     # TTY picker

Sets the active profile for gform run --auth. First created profile auto-activates.

list profiles

gform auth list
gform auth ls
gform auth list -j

Shows name, active marker, verify status, email, storage path.

verify

gform auth verify                     # TTY picker (active highlighted)
gform auth ver work
gform auth verify work --headless

Checks whether the saved session still looks signed-in. Updates meta.json with the verdict.

verdict	meaning	action
ok	signed in; email refreshed	ready for --auth runs
invalid	confirmed signed out	recreate: gform auth delete work --yes && gform auth create work
inconclusive	network/timeout/launch glitch	retry later — not marked logout

Exit code 1 on invalid or inconclusive.

view metadata

gform auth view                       # TTY picker (active highlighted)
gform auth v work
gform auth view -j

Profile details without secrets — verify timestamps, email, storage path.

delete

gform auth delete work
gform auth rm work -y                 # skip confirm (CI / non-TTY)

Removes profile storage. Does not delete forms or run artifacts — use clean.md for bulk auth purge.

use on run

gform run <form> --auth
gform run <form> --profile work
gform run <form> -A -pr work

Resolution: --profile → active → TTY picker → first profile (non-TTY).

browsers and --open

gform auth create work --open chrome
gform auth create work --open playwright

If the chosen browser is found but not ready (common for WSL → Windows .exe paths), gform warns — run gform browsers check chrome or gform browsers setup chrome. See browsers.md.

gotchas

• Playwright's bundled Chromium is often rejected by Google — prefer system Chrome via gform browsers default chrome.
• Duplicate Google accounts across profiles are blocked at create time.
• gform clean auth removes all profiles; auth delete removes one.
• Live verify in gform doctor --auth runs the same check for every profile.

related

• auth.md — deep dive on sessions and verify
• browsers.md — launch targets and setup
• run.md — --auth / --profile
• doctor.md — --auth live verify all profiles
• clean.md — purge auth storage