xlflow status

Show project, source, workbook, and session state in one read-only command.

Usage

xlflow status
xlflow status --json

Options and Arguments

Option / argument	Description	Default
--json	Return machine-readable state.	false

Examples

xlflow status --json

Notes

TIP

Use status before editing to confirm whether the saved workbook, live session, and source files are in sync.

TIP

AI agents should prefer xlflow status --json before pushing or running to avoid working against stale workbook state.

WARNING

src_newer_than_workbook is a heuristic based on file modification times. Clock skew or manual copies can cause false results.

status also distinguishes current lock ownership from recovery quarantine. busy: true means another xlflow operation owns the operating-system workbook lock. recovery_required: true means Excel-side completion is uncertain and unsafe workbook commands remain blocked even when busy is false.

JSON Output Example

{
  "status": "ok",
  "command": "status",
  "project": {
    "root": ".",
    "workbook_path": "build/Book.xlsm",
    "src_paths": ["src/modules", "src/classes", "src/forms", "src/workbook"],
    "project_name": "sample"
  },
  "session": {
    "active": false,
    "workbook_path": "build/Book.xlsm",
    "workbook_name": "Book.xlsm",
    "dirty": false,
    "running": false,
    "workbook_open": false,
    "metadata": null,
    "save_required": false,
    "live_newer_than_disk": false,
    "source_of_truth": "saved_workbook"
  },
  "coordination": {
    "busy": false,
    "recovery_required": false
  },
  "state": {
    "src_newer_than_workbook": false,
    "live_session_newer_than_disk": false,
    "workbook_saved": true,
    "source_of_truth": "saved_workbook",
    "workbook_last_modified_at": "2026-05-23T10:00:00Z",
    "latest_source_modified_at": "2026-05-22T10:00:00Z"
  },
  "warnings": [],
  "hints": [],
  "error": null,
  "logs": ["status reported"]
}

While recovery is required, status does not call unsafe workbook COM APIs. It reports session.dirty: null, session.source_of_truth: "uncertain", session.discard_required: true, and nested recovery details under coordination.recovery. Use recovery to choose a safe clearing path.

If recovery metadata cannot be read safely, status still does not report a clean workbook. It sets coordination.recovery_check_failed: true, keeps busy / recovery_required unknown (null), and reports the session/source of truth as uncertain.

Related

• session
• inspect
• push
• save
• recovery

When to use this command

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