xlflow pull

Export workbook VBA components and form artifacts into configured source directories.

Usage

xlflow pull [--backend auto|excel|file] [--session] [--formulas]

Options and Arguments

Option / argument	Description	Default
--session	Pull from the managed live session workbook.	false
--formulas	Also refresh worksheet formula snapshots under formulas/ on success.	false
--json	Report exported files and warnings.	false
--backend	Select auto, Excel/VBIDE excel, or pure-Go saved-workbook file.	auto

Examples

xlflow pull
xlflow pull --session --json
xlflow pull --formulas --json
xlflow pull --backend file --json

Notes

TIP

Pull before editing if the workbook may contain newer VBA than the source tree.

IMPORTANT

UserForm Designer state and code-behind may be written to separate sidecar paths depending on project configuration.

--backend file reads the saved configured .xlsm directly and never launches Excel, COM, VBIDE, or the bridge. It supports standard, class, and document modules plus UserForms in sidecar mode. UserForm Designer state is written to src/forms/specs/<Name>.yaml, code-behind to src/forms/code/<Name>.bas, and supported Image pictures to src/forms/assets/<full-SHA-256>.bmp|jpg. Compatibility .frm / .frx files are not generated or reconciled. Generated specs retain the compatibility_artifact_unsynchronized marker, but canonical FormSpec plus sidecar code is valid authority for push --backend file; stale compatibility files are ignored. The marker still blocks operations that select .frm code or compatibility files as import authority. Unsupported picture data stays in the workbook without a fabricated asset path. frm mode and Designer structures that cannot be parsed completely fail before modifying source. The file backend does not fall back to Excel and cannot be combined with --session. If a matching live session is recorded, the command still reads the saved workbook and warns that unsaved live state was ignored. Pulled pictures use content-addressed names and are not automatically deleted. Excel may normalize JPEG input to BMP when saving, so a pulled asset may be BMP.

The default auto mode chooses the fastest safe authority. A closed, supported .xlsm uses the file backend, including supported sidecar UserForms. --session, a valid matching session, a workbook open in local Excel, compatibility frm UserForm authority, or an Excel-supported format outside the file backend selects Excel. If Windows cannot determine open state, auto fails safe to an already-open matching Excel workbook and reports a warning; it does not open another copy from saved state. Use explicit --backend file or --backend excel when the authority must not be selected dynamically.

With [vba.line_numbers].enabled = true, pull strips only xlflow-generated, fixed-width space-padded physical line labels from workbook exports, so tracked source remains unnumbered. It never treats colon labels as generated. xlflow stops safely rather than rewriting source when it encounters non-generated or mismatched numeric labels, or numeric GoTo, GoSub, or Resume targets. This is configuration-only behavior; pull has no line-number flag.

--formulas runs the normal VBA pull first. If it succeeds, xlflow also extracts worksheet formulas, defined names, formula references, and parse summaries into formulas/.

Formula extraction reads the saved workbook file directly. When using pull --session --formulas, save the session first if formulas were changed only in the live workbook.

JSON Output Example

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

{
  "status": "ok",
  "command": "pull",
  "workbook": { "path": "build/Book.xlsm" },
  "pull": {
    "backend": "file",
    "backend_selection": "auto",
    "selection_reason": "file_backend_supported",
    "source": "saved_workbook",
    "code_page": 932,
    "modules": { "standard": 1, "class": 1, "document": 2, "form": 0 }
  },
  "source": { "written": ["src/modules/Main.bas"] },
  "output": {
    "formulas": {
      "dir": "formulas",
      "manifest": "formulas/manifest.json",
      "sheet_count": 2,
      "formula_region_count": 5,
      "parse_status_summary": {
        "ok": 4,
        "partial": 1,
        "failed": 0
      },
      "defined_name_count": 2
    }
  }
}

Related

• push
• diff
• project structure

When to use this command

Use xlflow pull 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

The default auto path does not require Excel for a closed, supported .xlsm, but may select it when live state or complete export requires it. Run xlflow doctor --json before forcing --backend excel. Explicit --backend file requires a readable configured saved .xlsm and does not require Excel or VBIDE.

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.