edit

Open a form YAML in your editor, or walk through answers interactively with --ask.

For the YAML contract (options, steps, pools, unique, variants), read schema. This page is the edit command only.

open in editor (default)

gform edit                         # TTY: pick a form
gform edit <form>
gform edit <form> --editor cursor
gform edit <form> --editor code
gform edit <form> --editor vim
gform edit ./forms/<form>.yaml
gform edit <form> --print          # resolved path only, no editor

Editor resolution: --editor → $EDITOR → auto-detect (cursor, code, nano, vim).

Bulk YAML edits happen here. Editor mode does not validate on save — run gform verify after (see schema).

After the editor closes successfully (default edit, or --ask --editor), gform prints an agent handoff block: paste into any coding agent so it reads agents + schema + this form path, asks how pools should vary, then edits. Not printed for --print or ask-only sessions.

interactive REPL (--ask)

gform edit <form> --ask
gform edit <form> --ask --editor code   # REPL first, then open editor

--ask menu:

• Form meta — name, url
• Options — starters + engine knobs (schema)
• Steps — edit / insert / delete / reorder / bulk answers & pools
• Preview changes — dirty-only; field-level diff + schema validity (Esc/Back reclaims)
• Save — dirty-only; validate then write (stamped header → schema). Main shows ✓ after
• Open in $EDITOR — optional; wall timer pauses while the editor is open
• Quit — receipt: Saved · …, No changes written, or discard warn

Ctrl+C / Ctrl+Z cancel the whole --ask session once ([warn] edit cancelled (SIGINT|SIGTSTP) + fail footer). Esc backs out silently (same as a Back / Done menu choice). At the top-level Main menu, Esc stays put and rings the terminal BEL — nowhere else to go.

Main prompt is compact: * Main (name) · N steps · rotate while dirty, ✓ Main … after a successful save this session. Preview / Save only appear when something actually changed.

when to use --ask

use --ask	use editor
first pass after gform init (fill placeholders)	adding many steps at once
tweaking a few answer values	copy-paste YAML from another form
setting up pool: for repeat runs	regex/search-replace across file
non-technical teammate filling answers	git diff review

header stamp

init, --ask Save, and restore rewrite the leading comment block to the short canonical header (points at schema). Stamping twice never stacks duplicates.

lookup

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

Resolves <form> against the override root, then cwd ./forms/, then library.

gotchas

• --print is useful in scripts: path=$(gform edit <form> --print).
• --ask only writes on Save (or save-before-editor) — Quit can discard.
• After editing, gform verify <form> before a headed demo run.
• Form starters (headed / repeat) lose to CLI/policy — details in schema.

related

• schema.md — form YAML contract
• init.md — scaffold then edit
• agents.md — coding-agent playbook + handoff context
• verify.md — validate after edits
• run.md — execute + provenance
• policies.md — named run --policy presets (not form YAML)
• repeat.md — pools and variant modes
• guide.md — workflow overview