xlflow module

Create, remove, rename, or install VBA module source files in an existing project.

Usage

xlflow module new <name> --type standard
xlflow module new <name> --type class
xlflow module remove <module-name>
xlflow module rename <old-name> <new-name>
xlflow module install [--push]

Options and Arguments

Option / argument	Description	Default
new <name>	Create a new standard or class module source file.	-
--type	Required for new; must be standard or class.	required
remove <module-name>	Remove a standard, class, or UserForm source module from the project.	-
rename <old-name> <new-name>	Rename a standard, class, or UserForm source module in the project.	-
install	Install the bundled helper modules into the configured module source root.	required
--push	Push the installed helper modules into the configured workbook after writing source files.	false

Examples

xlflow module new InvoiceProcessor --type standard
xlflow module new InvoiceService --type class --json
xlflow module remove InvoiceAggregator
xlflow module rename OldInvoiceService InvoiceService --json
xlflow module install
xlflow module install --push --json

Notes

TIP

module new --type standard writes [src].modules/<Name>.bas; module new --type class writes [src].classes/<Name>.cls.

TIP

module install writes XlflowAssert.bas, XlflowRuntime.bas, XlflowUI.bas, and XlflowDebug.bas into the configured [src].modules/Xlflow/ directory. It refuses both target collisions and legacy root-level helper collisions.

When installation reaches the shared source-preflight path (including module install --push), [preflight].allowed_diagnostics applies to registry blockers. File collisions and other non-registry integrity failures are not waivable.

WARNING

module new and module install refuse to overwrite existing source files. Remove or rename colliding files before retrying.

WARNING

module remove and module rename change source files only. Run xlflow push afterward to apply the change to the workbook.

TIP

UserForm remove/rename handles related source artifacts together: .frm, .frx, src/forms/code/<Name>.bas, and src/forms/specs/<Name>.yaml|yml|json when present.

WARNING

Workbook document modules such as ThisWorkbook and sheet modules are protected from module remove and module rename.

JSON Output Example

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

{
  "status": "ok",
  "command": "module new",
  "source": {
    "created": ["src/modules/InvoiceProcessor.bas"],
    "kind": "standard",
    "name": "InvoiceProcessor",
    "path": "src/modules/InvoiceProcessor.bas"
  }
}

{
  "status": "ok",
  "command": "module remove",
  "source": {
    "operation": "module.remove",
    "module": "InvoiceAggregator",
    "kind": "standard",
    "removed": ["src/modules/InvoiceAggregator.bas"],
    "requires_push": true
  }
}

{
  "status": "ok",
  "command": "module rename",
  "source": {
    "operation": "module.rename",
    "old_name": "OldInvoiceService",
    "new_name": "InvoiceService",
    "kind": "class",
    "renamed": [
      {
        "from": "src/classes/OldInvoiceService.cls",
        "to": "src/classes/InvoiceService.cls"
      }
    ],
    "requires_push": true
  }
}

{
  "status": "ok",
  "command": "module install",
  "source": {
    "created": [
      "src/modules/Xlflow/XlflowAssert.bas",
      "src/modules/Xlflow/XlflowRuntime.bas",
      "src/modules/Xlflow/XlflowUI.bas",
      "src/modules/Xlflow/XlflowDebug.bas"
    ]
  }
}

Related

• init
• new
• push

When to use this command

Use xlflow module 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.