xlflow

README

Excel VBA development, rebuilt for CLI-first humans and AI agents.

English | 日本語

🏄♂ xlflow

xlflow is an Excel VBA development framework for the AI agent era.

It turns .xlsm workbooks into a source-controlled, CLI-driven development workflow where VBA can be exported, edited, linted, imported, tested, traced, and executed from the command line.

[!TIP] Think of xlflow as a development harness around Excel VBA: it does not replace Excel, but it makes Excel VBA projects much easier to operate from terminals, scripts, CI-like local checks, and AI coding agents.

Demo

These samples were created by an AI agent using xlflow with only minimal natural language instructions.

Macro that summarizes world news in Excel using NewsAPI	Macro that retrieves stock prices and displays them in Excel
Macro that generates QR codes using cell colors and displays them in Excel	Macro that allows playing Tetris within Excel

---

Why xlflow?

Traditional VBA development is still heavily tied to the Excel UI and the Visual Basic Editor. That works for small manual edits, but it becomes painful when you want repeatable development, source control, tests, diffs, or AI-agent-assisted changes.

Pain in normal VBA development	What xlflow adds
VBA code is trapped inside .xlsm files	Export/import VBA as .bas, .cls, and .frm source files
Macro entrypoints are unclear	Discover runnable Public Sub procedures with xlflow macros
Runtime failures are hard to locate	Return structured errors, diagnostics, and trace logs
File dialogs and MsgBox block automation	Detect GUI boundaries before headless runs
Workbook changes are hard to review	Compare values, formulas, sheets, and exported VBA source
AI agents cannot safely operate Excel through the UI	Provide stable CLI commands and JSON output

pull → edit → push → lint → test/run → trace → diff

---

What xlflow can do

Area	Capabilities
Source control	Export and import standard modules, class modules, UserForms, and document modules
Execution	Run macros from the CLI with typed arguments
Testing	Discover and run VBA test procedures
Linting	Catch Option Explicit omissions, Select/Activate, broad error handling, implicit variants, public module fields, and interactive operations
GUI safety	Detect file pickers, input boxes, modal message boxes, and other automation-hostile boundaries
Debugging	Collect trace events and return runtime diagnostics
Diffing	Compare workbook cell values, formulas, sheet structure, and exported VBA source
AI agents	Return stable JSON and install bundled Skills for Codex, Claude, Cursor, Gemini, GitHub Copilot-style agent workflows, and other agents

[!IMPORTANT] xlflow is Windows-first. Workbook operations use Microsoft Excel + COM + PowerShell.

[!NOTE] Excel COM-backed commands report the xlflow bridge host in top-level bridge. If workbook VBA launches its own external PowerShell process, that host can still differ from xlflow's bridge host. Inspect or log the workbook-side executable when debugging powershell.exe vs pwsh.exe behavior.

---

Requirements

Requirement	Needed for
Windows	Excel COM automation
Microsoft Excel	new, init, pull, push, run, export-image, edit, test, macros, trace, doctor
PowerShell	Excel automation bridge
Trust access to the VBA project object model	Reading and writing VBA projects

[!NOTE] Commands that do not require Excel COM, such as lint, parts of diff, and Go unit tests, can be verified in non-Excel environments.

[!WARNING] In Excel, enable Trust access to the VBA project object model before using commands that read or write VBA code. Without it, pull, push, run, and related commands may fail even when Excel itself is installed.

Details

In Excel options, please enable "Trust Center" → "Macro Settings" → "Trust access to the VBA project object model".

---

Installation

Go install

go install github.com/harumiWeb/xlflow/cmd/xlflow@latest

go install may contact the Go module mirror and checksum database configured in your Go environment. For direct source checkout development and CI, treat the Go version declared in go.mod as the supported toolchain source of truth; the repository CI and release workflows resolve Go from that file.

Scoop

scoop bucket add harumiweb https://github.com/harumiWeb/scoop-bucket
scoop install xlflow

GitHub Releases

Download prebuilt Windows binaries from:

https://github.com/harumiWeb/xlflow/releases

[!IMPORTANT] Current prebuilt distribution targets Windows only. Commands that interact with workbooks still require Microsoft Excel, Excel COM automation, and Trust access to the VBA project object model. The release binary already embeds the runtime PowerShell bridge scripts, so xlflow.exe can run workbook commands without sidecar *.ps1 files.

Verify the downloaded ZIP against the published checksums.txt file:

Get-FileHash .\xlflow_windows_x86_64.zip -Algorithm SHA256
certutil -hashfile .\xlflow_windows_x86_64.zip SHA256

The reported SHA256 must match the entry for xlflow_windows_x86_64.zip in checksums.txt.

This confirms file integrity against the published checksum file. It does not prove publisher identity and is not a substitute for Windows Authenticode signing.

Verify the GitHub Actions provenance attestation with GitHub CLI:

gh attestation verify .\xlflow_windows_x86_64.zip --repo harumiWeb/xlflow

This confirms the artifact attestation published for the release artifact. It does not mean the ZIP is Authenticode-signed by a Windows publisher certificate.

Verify the installation:

xlflow version
xlflow --help

For development checkout usage:

go run ./cmd/xlflow --help

With Taskfile:

task run -- --help

---

Quick start

1. Create or initialize a project

Create a new xlflow project and macro-enabled workbook:

xlflow new Book.xlsm

Or start from an existing workbook:

xlflow init Book.xlsm

Install the AI agent Skill during project creation:

xlflow new Book.xlsm --with-skill --agent codex

Interactive xlflow new and xlflow init render a welcome banner and may check the latest GitHub Release through the GitHub Releases API. Disable that request for one invocation with --no-update-check, or set XLFLOW_NO_UPDATE_CHECK=1 to disable it for interactive scaffolding in your environment.

2. Check the Excel automation environment

xlflow doctor --json

[!TIP] If pull, push, run, or test fails because of Excel, COM, PowerShell, or VBIDE settings, run doctor first.

3. Export VBA into source files

xlflow pull --json

Edit the exported .bas, .cls, and .frm files under src/ with your normal editor. When folder mode is enabled, nested directories under each configured source root are mapped to Rubberduck-compatible @Folder(...) annotations during push.

4. Import edited source back into the workbook

xlflow push --json

5. Discover and run macros

xlflow macros --json
xlflow run Main.Run --json

For unattended automation, prefer headless mode:

xlflow run Main.Run --headless --json

If the macro intentionally shows file pickers, message boxes, or UserForms, use interactive mode:

xlflow run Main.Run --interactive --timeout 5m --json

6. Lint and test

xlflow lint --json
xlflow test --json

---

Common workflows

AI-agent-assisted VBA editing

1. Read xlflow.toml
2. Start xlflow session start for normal editing work
3. If the latest source of truth is unclear, run xlflow pull --session --json
4. Edit files under src/
5. Run xlflow push --fast --session --no-save --json
6. Run xlflow lint --json
7. Run xlflow test --session --json
8. Run xlflow macros --session --json
9. Run xlflow run <qualified_name> --headless --session --json
10. Use xlflow run --trace --session --json when runtime failures are unclear
11. Run xlflow save --session --json before xlflow session stop
12. Use xlflow diff --json when workbook changes must be reviewed

[!IMPORTANT] AI agents and CI-like scripts should prefer --json. The JSON envelope is designed to be stable and easier to parse than human-readable output. xlflow run now compiles VBA and returns structured compile diagnostics by default. Use --gui-compile-errors only when a human explicitly wants raw Excel/VBE dialogs.

Human-assisted Excel sessions

Use attach when a human has Excel open and you want to validate the active workbook before working with it:

xlflow attach --active --json

[!NOTE] attach is a safety check. It confirms that the active Excel workbook matches the configured excel.path; it does not change the target used by pull, push, or run.

GUI-heavy macros

Inspect GUI boundaries before deciding whether a macro can run headlessly:

xlflow inspect-gui --json

Result	Suggested mode
No GUI boundaries	xlflow run ... --headless --json
File picker, InputBox, modal MsgBox, or UserForm detected	xlflow run ... --interactive --timeout 5m --json
GUI code wraps core logic	Refactor core logic into parameterized headless procedures

[!WARNING] Headless automation and modal Excel UI do not mix. Use inspect-gui before unattended runs and keep GUI entrypoints thin.

---

Command map

Command	Purpose	Typical usage
new	Create a new xlflow project and .xlsm workbook	xlflow new Book.xlsm
init	Initialize xlflow from an existing workbook	xlflow init Book.xlsm
doctor	Diagnose Excel, COM, PowerShell, and VBIDE access	xlflow doctor --json
attach	Validate the workbook currently active in Excel	xlflow attach --active --json
pull	Export VBA components into src/	xlflow pull --json
push	Import VBA source back into the workbook	xlflow push --json
session	Keep the configured workbook open for fast loops	xlflow session start
save	Save the workbook held by a session	xlflow save --session --json
runner	Manage the persistent xlflow runner marker module	xlflow runner install --json
macros	Discover runnable macro entrypoints	xlflow macros --json
run	Execute a macro from the CLI	xlflow run Main.Run --json
export-image	Export a worksheet range to a PNG image	xlflow export-image --sheet QR --range A1:AE31 --json
edit	Mutate a live session workbook for setup and tuning	xlflow edit cell --sheet Input --cell B2 --value ABC123 --session --json
trace	Enable, collect, and clean VBA trace logs	xlflow trace enable --json
test	Run VBA tests	xlflow test --json
diff	Compare workbook content and optional VBA source	xlflow diff before.xlsm after.xlsm --json
inspect	Inspect saved workbook snapshots without Excel COM	xlflow inspect range --sheet Result --address A1:F20 --json
lint	Lint VBA source	xlflow lint --json
analyze	Analyze runtime-risk patterns without opening Excel	xlflow analyze --json
check	Run lint, analyze, and doctor as a preflight	xlflow check --keepalive --json
inspect-gui	Detect GUI interaction boundaries	xlflow inspect-gui --json
skill install	Install the bundled xlflow Skill for AI agents	xlflow skill install --agent codex
version	Show the installed xlflow build metadata	xlflow version

---

Commands in detail

Project setup: new, init, doctor, attach

xlflow new

Creates a new xlflow project and .xlsm workbook.

xlflow new
xlflow new Sales
xlflow new Sales.xlsm

When no argument is provided, xlflow creates build/Book.xlsm. When the name has no extension, .xlsm is appended. new creates a macro-enabled workbook, so extensions other than .xlsm are rejected. Pass --no-update-check when you want to skip the interactive GitHub Release lookup during scaffolding.

new creates the project structure, including xlflow.toml, src/, tests/, build/, and .xlflow/. It also creates or updates .gitignore to ignore Excel temporary files and xlflow-generated artifacts.

xlflow init

Creates an xlflow project from an existing Excel workbook.

xlflow init Book.xlsm

The given workbook is copied under build/, and its project-local path is recorded in [excel].path in xlflow.toml. Pass --no-update-check when you want to skip the interactive GitHub Release lookup during scaffolding.

xlflow doctor

Diagnoses the Excel automation environment.

xlflow doctor --json

It checks whether Excel is installed, whether the workbook can be opened, and whether VBIDE access is available. When source files are available, doctor also reports GUI boundary candidates that may block headless runs.

xlflow attach

Validates the workbook currently active in Excel.

xlflow attach --active --json

This is useful for human-assisted sessions where Excel is already open.

VBA source loop: pull, push, macros, run

xlflow pull

Exports VBA components from the configured workbook.

xlflow pull --json

It exports standard modules, class modules, UserForms, and document modules such as Workbook and Worksheet modules into src/. Use xlflow pull --session --json when you want to require the recorded session workbook explicitly. If .xlflow/session.json already points at the configured workbook, plain xlflow pull --json auto-reuses that matching live workbook.

xlflow push

Imports VBA source under src/ back into the Excel workbook.

xlflow push --json

It reads .bas, .cls, and .frm files and imports them through VBIDE. UserForm .frx files are treated as binary companion files. By default, push creates a backup under .xlflow/backups and saves the workbook.

For faster development loops:

xlflow push --fast --json
xlflow push --changed-only --json
xlflow push --backup=never --json

--fast is shorthand for --backup=never --changed-only. When --changed-only sees the same source fingerprint in .xlflow/state/push.json, xlflow skips Excel/VBIDE import.

xlflow macros

Discovers runnable Public Sub entrypoints.

xlflow macros --json

[!TIP] AI agents and automation scripts should run this command before guessing a macro name. Use the returned qualified_name with xlflow run to avoid entrypoint mistakes. During session-based development, xlflow macros --json already auto-reuses a matching recorded session workbook; add --session when you want that requirement to be explicit.

xlflow run

Runs a macro from the CLI.

xlflow run Main.Run --json

Macros with arguments are supported:

xlflow run Report.Generate \
  --arg string:fixtures\sample.xlsx \
  --arg int:3 \
  --arg bool:true \
  --json

--arg accepts typed arguments with string:, int:, and bool: prefixes. Empty values are allowed only for string:.

By default, run does not save the workbook. To persist results, explicitly pass --save or --save-as.

xlflow run Report.Generate --save --json
xlflow run Report.Generate --save-as build\Result.xlsm --json

When execution fails, xlflow returns macro_failed or macro_not_found with VBA error number, description, module name, phase, and line number when available. Runtime failures also include run_diagnostic when xlflow can match the failure to nearby source or a known VBA pattern such as a missing Set assignment. By default, run compiles the VBA project first and converts VBE compile dialogs into structured vba_compile_failed JSON with module, line, column, message, and nearby code when available. Use --gui-compile-errors only when you intentionally want Excel/VBE compile dialogs to appear instead.

Mode	Behavior
--headless	Rejects GUI boundaries before Excel starts and returns gui_boundary_detected with top-level gui_boundaries
--interactive	Runs with Excel visible and alerts enabled for human operation
--direct	Runs an argument-free, trace-disabled macro without temporary harness injection; plain --direct auto-disables default compile diagnostics
--fast	Uses direct execution when eligible and diagnostic mode is disabled, otherwise falls back to normal run
--diagnostic	Explicitly keeps structured compile diagnostics enabled (default true)
--gui-compile-errors	Opts out of structured compile diagnostics and allows Excel/VBE compile dialogs to appear
--session	Uses the workbook opened by xlflow session start
--timeout 5m	Stops execution if it does not complete in time and returns macro_timeout

xlflow session

Keeps Excel and the configured workbook open between commands:

xlflow session start
xlflow pull --session --json   # when the workbook may be newer than src/
xlflow push --fast --session --no-save --json
xlflow run Main.Run --headless --session --json
xlflow save --session --json
xlflow session stop

--session remains the explicit assertion mode. When .xlflow/session.json already points at the configured workbook, plain pull, push, macros, run, export-image, test, trace, and save auto-reuse that matching live workbook and report that reuse in JSON and human output.

When push --session --no-save succeeds, or run --session completes without --save / --save-as, the live workbook may differ from the .xlsm on disk until xlflow save --session. xlflow now warns more aggressively about this unsaved session state, but xlflow save --session remains the canonical persistence step before session stop.

Debugging and testing: trace, test, diff

xlflow trace

Collects log events from VBA during macro execution.

Enable the trace module when you want it persisted in the workbook and source tree:

xlflow trace enable --json
xlflow trace status --json

During session-based development, add --session to trace enable, trace status, trace disable, and traced run commands.

Write logs from VBA:

Call XlflowLog("start GenerateReport")
Call XlflowLog("lastRow=" & lastRow)
Call XlflowLog("finished GenerateReport")

Run the macro with trace enabled:

xlflow run Main.Run --trace --json

Trace events are returned in the top-level JSON trace field. This helps identify how far execution progressed before a runtime error.

xlflow run --trace can temporarily inject and revert the helper when it is missing. Human output and JSON trace.lifecycle distinguish that temporary path from a helper that is already persisted in workbook/source state. Trace logs are written under .xlflow/traces. Use xlflow trace disable --json to remove the persistent helper and xlflow trace clean --json to remove trace log files. xlflow trace inject remains as a compatibility alias for trace enable.

xlflow test

Runs VBA tests.

xlflow test --json

xlflow discovers argument-free Sub procedures whose names start with Test or end with _Test. Use xlflow test --session --json when an xlflow session is already open.

To run a single test, use --filter:

xlflow test --filter TestCreateReport --json

New and initialized projects include src/modules/XlflowAssert.bas. Use AssertEquals expected, actual, [message] to compare scalar values.

Public Sub TestCreateReport()
    AssertEquals 10, Sheets("Result").Range("A1").Value2
End Sub

[!NOTE] AssertEquals does not support object or array comparison. Compare scalar properties such as Range.Value2 instead of passing Range objects directly.

xlflow diff

Compares two workbooks.

xlflow diff before.xlsm after.xlsm --json

It detects sheet additions/removals, cell value differences, and formula differences.

To compare exported VBA source as well, pass --vba-before and --vba-after:

xlflow diff before.xlsm after.xlsm \
  --vba-before before-src \
  --vba-after after-src \
  --json

[!IMPORTANT] Differences are reported as successful command results. diff returns exit code 0 even when differences are found. Inspect diff.summary.total_diffs in JSON to determine whether anything changed.

Quality gates: lint, analyze, check, inspect-gui

xlflow lint

Lints VBA source.

xlflow lint --json

It detects patterns that are unsafe or inconvenient for AI agents and unattended automation:

• Missing Option Explicit
• Select usage
• Activate usage
• On Error Resume Next usage
• Possible implicit Variant
• Module-level Public variables
• Interactive operations such as Application.GetOpenFilename, Application.FileDialog, InputBox, and modal MsgBox

xlflow analyze

Analyzes VBA source for runtime-risk patterns without opening Excel.

xlflow analyze --json

The first analyzer rules report likely missing Set assignments for object variables and object-returning functions. Findings are returned in top-level analysis with file, module, procedure, line, nearby code, reason, and suggestion.

xlflow check

Runs the standard preflight sequence:

xlflow check --keepalive --json

check runs lint, analyze, and doctor, then returns an aggregate top-level check object. It continues after lint/analyze findings so the report includes all cheap source feedback before the Excel COM doctor result.

xlflow inspect

Reads the saved workbook file directly without opening Excel.

xlflow inspect workbook --json
xlflow inspect sheets --format markdown
xlflow inspect range --sheet "Result" --address "A1:F20" --json
xlflow inspect range --sheet "QR" --address "A1:AE31" --include-style --json
xlflow inspect used-range "Result" --max-rows 50 --max-cols 10 --format markdown
xlflow inspect cell "Result!B3" --json

Use it to inspect workbook structure and cell output after push / run workflows when the workbook state has been saved to disk. inspect is a file snapshot reader, so unsaved changes in an already-open Excel window are intentionally out of scope for this command family. Add --include-style on inspect range or inspect used-range when the workbook meaning depends on fill colors, borders, merged cells, row heights, or column widths.

xlflow export-image

Exports a worksheet range as a PNG through Excel COM.

xlflow export-image --sheet "QR" --range "A1:AE31" --json
xlflow export-image --sheet "QR" --range "A1:AE31" --out artifacts\qr.png --overwrite --json

This is the visual verification companion to inspect. Use it when workbook correctness depends on charts, fills, layout, printable forms, QR-code cells, or other rendering details that a saved-file snapshot is not enough to prove.

Without --out, xlflow writes under .xlflow/artifacts/images/<workbook-name>/ using a generated filename. --output-dir selects only the directory, and --name selects only the filename. Only PNG is supported in v1.

Like other workbook-backed commands, export-image auto-reuses a matching recorded session workbook when .xlflow/session.json points at the configured workbook. Add --session when you want that requirement to be explicit. Successful JSON includes top-level target, output, and optional warnings.

xlflow edit

Mutates the live workbook held by an xlflow session for development-time setup and visual tuning.

xlflow edit cell --sheet "Input" --cell "B2" --value "ABC123" --events on --session --json
xlflow edit range --sheet "QR" --range "A1:AE31" --fill "#FFFFFF" --session --json
xlflow edit rows --sheet "QR" --rows "1:31" --height 12 --session --json
xlflow edit columns --sheet "QR" --columns "A:AE" --width 2.2 --session --json

Use it to prepare workbook state before run, trigger Worksheet_Change handlers with --events on, clear or repaint regions between iterations, and tune row heights or column widths before exporting an image. MVP edit is intentionally session-only: --session is required, successful edits mark the live workbook dirty, and you must run xlflow save --session to persist the changes to disk.

xlflow inspect-gui

Reports GUI interaction boundaries without opening Excel.

xlflow inspect-gui --json

The report includes file, line, kind, symbol, and a suggested refactor. Use it before deciding whether a macro should run with --headless or --interactive.

AI agent support: skill install

xlflow skill install

Installs the bundled xlflow Skill for AI agents.

xlflow skill install --agent codex
xlflow skill install --agent claude
xlflow skill install --agent cursor
xlflow skill install --agent gemini
xlflow skill install --target .agents/skills

Supported provider targets are:

Agent target	Install path
agents	.agents/skills/xlflow
codex	.codex/skills/xlflow
claude	.claude/skills/xlflow
cursor	.cursor/skills/xlflow
gemini	.gemini/skills/xlflow

For GitHub Copilot-style workflows, use the shared .agents target:

xlflow skill install --agent agents

---

Configuration

xlflow reads xlflow.toml from the project root.

[project]
name = "sample"
entry = "Main.Run"

[excel]
path = "build/Book.xlsm"
visible = false
display_alerts = false

[src]
modules = "src/modules"
classes = "src/classes"
forms = "src/forms"
workbook = "src/workbook"

[vba]
folders = true
folder_annotation = "update"
default_component_folders = true

[lint]
require_option_explicit = true
forbid_select = true
forbid_activate = true
forbid_on_error_resume_next = true
detect_implicit_variant = true
forbid_public_module_fields = true
forbid_interactive_input = true

project.entry is used when xlflow run is invoked without a macro name.

---

JSON output

Every command can return AI-agent-friendly JSON by passing --json.

The basic envelope is:

{
  "status": "ok",
  "command": "lint",
  "error": null,
  "logs": []
}

On failure, status is failed, and error.code and error.message are returned.

{
  "status": "failed",
  "command": "run",
  "error": {
    "code": "macro_failed",
    "message": "Main Err 5: inputPath is required",
    "source": "Main",
    "number": 5,
    "phase": "invoke_macro"
  },
  "logs": []
}

[!TIP] AI agents and automation scripts should treat status, command, error.code, and command-specific top-level fields as the primary contract.

---

Exit codes

Code	Meaning
0	Success
1	Validation failure, such as lint, macro, or test failure
2	CLI argument or configuration error
3	Environment error, such as Excel, COM, VBIDE, or PowerShell failure

[!NOTE] diff returns exit code 0 even when differences are found. Inspect diff.summary.total_diffs to determine whether inputs differ.

---

Recommended VBA rules

VBA executed by xlflow should be written for unattended automation.

• Always use Option Explicit
• Use explicit Workbook, Worksheet, and Range references
• Prefer Long over Integer
• Keep GUI entrypoints thin
• Extract parameterized headless procedures for the core logic
• Pass input values through xlflow run --arg, configuration files, deterministic paths, or environment variables
• Emit error messages that make failures diagnosable
• Verify destructive workbook changes with tests or diff
• Do not rely on Select, Activate, or ActiveSheet
• Do not depend on UI dialogs or modal MsgBox in headless procedures
• Avoid broad On Error Resume Next

---

Local verification

Run repository linters with:

task lint

task lint runs golangci-lint run and PSScriptAnalyzer against tracked .ps1 sources. Make sure Invoke-ScriptAnalyzer is available in your local PowerShell environment.

Run the fast repository verification with:

task verify

Currently, task verify runs go test ./... as non-COM test coverage.

Excel COM E2E verification should be run on Windows with Excel and VBIDE access enabled.

xlflow doctor --json

After doctor reports a healthy environment, run new, doctor, pull, lint, push, run, test, and diff against a real workbook.

---

Current status

xlflow is an MVP-stage tool.

Its primary goal is to bring Excel VBA into AI-agent and CLI-based development workflows. Typical use cases include:

Use case	Why xlflow helps
Source control for existing VBA	VBA modules become normal files
AI-agent-assisted VBA modification	Agents can edit source, run checks, and inspect JSON output
CLI execution of Excel macros	Macros can be invoked from scripts and terminals
Automated VBA testing	Tests can be discovered and executed consistently
Debugging with runtime logs	Trace events show how far execution progressed
Workbook change review	diff makes workbook changes easier to inspect
Internal Excel automation	Existing VBA assets can move toward safer development workflows

[!CAUTION] xlflow is useful, but it cannot make every legacy workbook safely headless. GUI-heavy macros, workbook-level side effects, external dependencies, and fragile Excel state still need deliberate refactoring.

---

License

MIT