xl

Agent-first CLI for Excel workbooks (.xlsx / .xlsm)

A transactional spreadsheet execution layer that lets AI agents and humans inspect, plan, validate, and apply workbook changes deterministically — like terraform for Excel.

xl wb inspect -f budget.xlsx          # discover structure
xl plan add-column -f budget.xlsx \   # generate a plan (non-mutating)
   -t Sales -n Margin \
   --formula "=[@Revenue]-[@Cost]" \
   --out plan.json
xl validate plan -f budget.xlsx \     # check before applying
   --plan plan.json
xl apply -f budget.xlsx \             # preview changes
   --plan plan.json --dry-run
xl apply -f budget.xlsx \             # apply with safety backup
   --plan plan.json --backup
xl verify assert -f budget.xlsx \     # confirm expected state
   --assertions '[{"type":"table.column_exists","table":"Sales","column":"Margin"}]'

Every command returns a structured JSON envelope:

{
  "ok": true,
  "command": "table.ls",
  "result": [...],
  "errors": [],
  "warnings": [],
  "metrics": { "duration_ms": 42 }
}

No Excel installation required — works entirely with openpyxl.

Features

• Inspect — sheets, tables, named ranges, fingerprints, lock status
• Read — cell values, range statistics (min/max/mean/sum/count/stddev), formula search by regex
• Query — SQL over table data via DuckDB (SELECT Region, SUM(Sales) FROM Sales GROUP BY Region)
• Mutate — add/delete columns, append rows, set cells/formulas, number formats, column widths, freeze panes
• Patch plans — generate JSON plans, compose multi-step plans, validate before applying
• Apply — execute plans with --dry-run preview and --backup safety copy
• Verify — post-apply assertions (table.column_exists, cell.value_equals, row_count.gte, ...)
• Diff — cell-level comparison between two workbook files
• Lint — detect volatile functions, broken references, formula anti-patterns
• Workflows — multi-step YAML pipelines with xl run
• Server mode — stdio JSON server for agent tool integration (MCP/ACP)

Safety rails

All mutating commands include built-in protections:

Installation

Requires Python 3.12+ and uv.

From PyPI (recommended)

uv tool install xl-agent-cli

# Verify
xl version
xl --help

One-shot with uvx

uvx --from xl-agent-cli xl --help

Local development install

git clone https://github.com/ThomasRohde/xl-cli.git
cd xl-cli
uv sync

# Verify
uv run xl version
uv run xl --help

Global install from source

git clone https://github.com/ThomasRohde/xl-cli.git
cd xl-cli
uv tool install --from . xl-agent-cli

If xl is not found, open a new terminal so your PATH refreshes.

Quick start

1. Inspect a workbook

xl wb inspect -f data.xlsx

Returns sheets, tables (with columns and row counts), named ranges, and a fingerprint hash.

2. List tables

xl table ls -f data.xlsx

3. Query with SQL

xl query -f data.xlsx \
  --sql "SELECT Region, SUM(Revenue) as Total FROM Sales GROUP BY Region ORDER BY Total DESC"

4. Add a calculated column (safe workflow)

# Generate a plan (does NOT modify the workbook)
xl plan add-column -f data.xlsx -t Sales -n GrossMarginPct \
  --formula "=[@GrossMargin]/[@Revenue]" \
  --out plan.json

# Validate the plan
xl validate plan -f data.xlsx --plan plan.json

# Preview what would change
xl apply -f data.xlsx --plan plan.json --dry-run

# Apply for real with backup
xl apply -f data.xlsx --plan plan.json --backup

# Verify the result
xl verify assert -f data.xlsx \
  --assertions '[{"type":"table.column_exists","table":"Sales","column":"GrossMarginPct"}]'

5. Format a report

xl format number -f report.xlsx --ref "Sales[Revenue]" --style currency --decimals 2
xl format width -f report.xlsx --sheet Sheet1 --columns A,B,C,D --width 15
xl format freeze -f report.xlsx --sheet Sheet1 --ref B2

6. Compare before and after

xl diff compare --file-a original.xlsx --file-b modified.xlsx

Command reference

Use xl <group> --help or xl <group> <command> --help for detailed usage.

Reference syntax

Commands that target cells, ranges, or table columns use ref syntax:

Exit codes

Agent integration

xl is designed to be driven by AI coding agents. Every command returns machine-parseable JSON, uses deterministic exit codes, and provides progressive discovery:

xl guide                        # full structured JSON orientation (start here)
xl --help                       # command group overview
xl table --help                 # group detail with examples
xl table add-column --help      # command detail with usage examples

Token-optimized help (TOON)

When an LLM drives the CLI, verbose Rich-formatted --help output wastes tokens. Set LLM=true to switch all help to TOON (Token-Oriented Object Notation) — a compact key:value format that cuts token usage by ~75%.

# Enable TOON for the session
export LLM=true          # bash/zsh
$env:LLM = "true"        # PowerShell

xl --help

name: xl
description: Agent-first CLI for reading transforming and validating Excel workbooks
options[2]:
  flag,type,required,default,help
  --version/-V,flag,false,false,Print version and exit.
  --human,flag,false,false,Force human-readable help (overrides LLM=true).
groups[11]:
  name,description
  cell,Read and write individual cell values.
  table,Table operations — list add columns append rows.
  ...

The --human flag overrides LLM=true for a single invocation:

xl --human --help         # Rich output even with LLM=true set

stdio server mode

For tool-use integrations (MCP, ACP, or custom):

xl serve --stdio

Reads JSON commands from stdin, writes JSON responses to stdout.

Development

# Install with dev dependencies
uv sync

# Run all tests
uv run pytest tests/ -v

# Run a specific test file
uv run pytest tests/test_cli.py -v

# Run the CLI directly
uv run xl --help

Tech stack

Project structure

src/xl/
├── cli.py                  # Typer CLI app, all command definitions
├── contracts/              # Pydantic models (ResponseEnvelope, PatchPlan, WorkflowSpec)
├── engine/                 # WorkbookContext, response dispatcher, verify, workflow runner
├── adapters/               # openpyxl engine, DuckDB queries
├── validation/             # Plan/workbook validators, policy engine
├── io/                     # Fingerprint, backup, atomic write, file locking
├── observe/                # Timer and event utilities
├── diff/                   # Workbook comparison logic
├── help/                   # TOON help output for LLM consumers
└── server/                 # stdio server mode

tests/                      # Unit, integration, golden, property, performance tests

License

MIT