xlflow form

Manage UserForms through sidecar scaffolds, Designer snapshots, rebuilds, and image export.

Usage

xlflow form new <name>
xlflow [--wait] form migrate sidecar [FormName] [--overwrite]
xlflow [--wait] form snapshot <name> --out <path>
xlflow [--wait] form build <spec> [--overwrite]
xlflow [--wait] form export-image <name> --out <png>

Options and Arguments

Option / argument	Description	Default
new <name>	Create sidecar UserForm code/spec source files.	-
migrate sidecar	Convert frm-mode UserForms to sidecar code and Designer specs.	-
snapshot <name>	Save Designer state as JSON or YAML.	-
build <spec>	Create or update a UserForm from a saved spec.	-
export-image <name>	Render a runtime UserForm to PNG.	-
--out <path>	Output path for snapshots or images.	-
--overwrite	Allow replacing an existing UserForm on build.	false
--session	Operate against the managed live session workbook.	false
--no-save	Leave session-backed build changes unsaved until xlflow save.	false
--initializer <mode>	Control initializer execution for image export.	default
--wait	Wait up to 30 seconds for the configured workbook lock.	false
--wait-timeout <d>	Override the positive bounded wait duration; requires --wait.	30s

form snapshot reads the design-time Designer state without loading the form at runtime or running workbook VBA. Controls created only by runtime code are visible through runtime inspection or image export, not through snapshot.

form new is source-only and requires [userform].code_source = "sidecar". It creates [src].forms/code/<Name>.bas and an authoring-focused [src].forms/specs/<Name>.yaml (defaulting to src/forms/...); blank specs omit snapshot-only fields such as warnings. It does not create .frm or .frx artifacts.

Workbook-writing sidecar form flows use the shared source-preflight policy. Registry blockers listed in [preflight].allowed_diagnostics can proceed with aggregated warnings, one per waived diagnostic ID with occurrence counts aggregated within each warning. Malformed specs, FRM... / UFY... artifact integrity failures, unreadable source, and other non-registry failures remain blocking.

Edit Designer specifications directly under src/forms/specs/ to receive real-time UserForm YAML diagnostics, context-aware completion, and Hover documentation from xlflow lsp. Hover distinguishes supported fields from best-effort geometry, observed-only list state, snapshot metadata, and custom/unchecked fields before form build opens Excel.

All other workbook-backed form commands share the configured workbook lock with run, test, push, pull, and Designer inspection. Contention returns workbook_busy before Excel or VBIDE starts. Use global --wait for an explicit bounded retry; form new rejects waiting because it changes source files only.

form migrate sidecar converts existing tracked src/forms/*.frm UserForms to the sidecar layout. It extracts code-behind to src/forms/code/<Name>.bas, writes a non-executing Designer spec to src/forms/specs/<Name>.yaml, and switches [userform].code_source to "sidecar" after all selected forms succeed. Pass a form name to migrate one form. Existing Designer spec files always require --overwrite; existing sidecar code can be skipped only when it already matches the extracted .frm code.

Because the Designer spec is captured from the configured workbook, migration refuses to run when source files are newer than the workbook. Run xlflow push to apply source-only UserForm edits first, or xlflow pull if the workbook should remain authoritative.

Examples

xlflow form new CustomerForm --json
xlflow form migrate sidecar --json
xlflow form migrate sidecar CalendarForm --overwrite --json
xlflow form snapshot CalendarForm --out src/forms/specs/CalendarForm.yaml --json
xlflow form build src/forms/specs/CalendarForm.yaml --overwrite --json
xlflow form export-image CalendarForm --out artifacts/CalendarForm.png --json
xlflow --wait --wait-timeout 15s form snapshot CalendarForm --out artifacts/CalendarForm.yaml --json

Notes

IMPORTANT

The canonical Designer source is src/forms/specs/*.yaml or *.json; sidecar code lives separately under src/forms/code/.

TIP

Prefer the built-in first-class control types and their suggested ProgIDs. A custom progId remains compatible, but xlflow can validate only common structure; type-specific properties and Designer compatibility depend on the installed ActiveX control.

WARNING

form new refuses to overwrite an existing sidecar code or spec file. In frm code-source mode, use form snapshot / form build workflows or switch the project to sidecar mode intentionally.

[!WARNING] form migrate sidecar keeps .frm and .frx artifacts in place. After migration, edit Designer structure in src/forms/specs/*.yaml and code-behind in src/forms/code/*.bas; treat .frm / .frx as generated artifacts.

[!WARNING] form export-image depends on desktop Excel GUI behavior and may execute UserForm_Initialize depending on initializer settings.

JSON Output Example

Successful --json output uses the xlflow envelope plus command-specific fields.

{
  "status": "ok",
  "command": "form new",
  "source": {
    "created": ["src/forms/code/CustomerForm.bas", "src/forms/specs/CustomerForm.yaml"],
    "kind": "form",
    "name": "CustomerForm",
    "code_path": "src/forms/code/CustomerForm.bas",
    "spec_path": "src/forms/specs/CustomerForm.yaml",
    "code_source": "sidecar"
  }
}

{
  "status": "ok",
  "command": "form migrate sidecar",
  "source": {
    "operation": "userform.migrate_sidecar",
    "code_source_before": "frm",
    "code_source_after": "sidecar",
    "forms": [
      {
        "name": "CalendarForm",
        "frm_path": "src/forms/CalendarForm.frm",
        "frx_path": "src/forms/CalendarForm.frx",
        "code_path": "src/forms/code/CalendarForm.bas",
        "spec_path": "src/forms/specs/CalendarForm.yaml"
      }
    ],
    "created": ["src/forms/code/CalendarForm.bas", "src/forms/specs/CalendarForm.yaml"],
    "updated": ["xlflow.toml"],
    "skipped": [],
    "config_path": "xlflow.toml",
    "requires_push": false
  }
}

{
  "status": "ok",
  "command": "form build",
  "form": "CalendarForm",
  "designer": "src/forms/specs/CalendarForm.yaml",
  "overwritten": true
}

Related

• list
• inspect form
• UserForm specification

When to use this command

Use xlflow form when the task matches the command description above. For a goal-oriented workflow, start with the How-to guides and return here for exact options.

Prerequisites

Check the project configuration and run xlflow doctor --json before workbook-backed operations. Source-only commands can run without Excel; commands that read or mutate a workbook require Windows Excel and VBIDE access.

What this command reads and changes

The command reads the inputs and configuration described in its syntax and examples. Treat source files, the saved workbook, and a live session as separate states; add --session when the live workbook is authoritative. Any mutation is reversible only when a backup or explicit session save boundary exists.

Effect on source-of-truth state

Use xlflow status --json before and after the command. A source edit normally requires push; a workbook edit normally requires pull; a dirty live session requires save --session or an intentional discard.

Common workflows

Combine this command with the relevant source/workbook/session workflow, and use --json in scripts and agent loops.

Common failures

Read the structured error.code, exit code, and recovery metadata instead of scraping terminal text. The symptom-oriented troubleshooting guide maps installation, execution, session, VS Code, and WSL failures to recovery steps.