Skip to content
agent-xlsx

Commands

All commands return JSON to stdout by default. When using --format csv or --format markdown, raw text is written to stdout instead. Use agent-xlsx <command> -h for help on any command.

agent-xlsx probe <file>                     # Profile workbook structure
agent-xlsx read <file> [range]              # Extract data (Polars, fast)
agent-xlsx search <file> <query>            # Find values across sheets
agent-xlsx export <file>                    # Bulk export (CSV/JSON/Markdown)
agent-xlsx overview <file>                  # Structural metadata
agent-xlsx inspect <file>                   # Deep metadata inspection
agent-xlsx format <file> <range>            # Read/write cell formatting
agent-xlsx write <file> <cell> [value]      # Write values or formulas
agent-xlsx sheet <file>                     # Manage sheets
agent-xlsx screenshot <file> [range]        # HD PNG capture
agent-xlsx objects <file>                   # Embedded objects
agent-xlsx recalc <file>                    # Formula error checking
agent-xlsx vba <file>                       # VBA macro analysis
agent-xlsx license                          # Aspose licence management

Error handling

All errors return structured JSON with an error code, message, and actionable suggestions:

{
  "error": true,
  "code": "FILE_NOT_FOUND",
  "message": "File not found: missing.xlsx",
  "suggestions": [
    "Check the file path is correct",
    "Ensure the file exists and is readable"
  ]
}

Error codes: FILE_NOT_FOUND, INVALID_FORMAT, SHEET_NOT_FOUND, RANGE_INVALID, INVALID_REGEX, EXCEL_REQUIRED, ASPOSE_NOT_INSTALLED, LIBREOFFICE_REQUIRED, NO_RENDERING_BACKEND, MEMORY_EXCEEDED, VBA_NOT_FOUND, CHART_NOT_FOUND.

Probe

Profile workbook structure. Run first, always. Uses fastexcel with zero data parsing by default.

agent-xlsx probe <file>                          # Lean: sheet names, dims, headers, column_map
agent-xlsx probe <file> --types                  # + column types, null counts
agent-xlsx probe <file> --sample 3               # + 3 head + 3 tail rows
agent-xlsx probe <file> --stats                  # + numeric/string summaries (implies --types)
agent-xlsx probe <file> --full                   # Everything: types + sample(3) + stats
agent-xlsx probe <file> --sheet "Sales" --full   # Single-sheet deep-dive
agent-xlsx probe <file> --no-header              # Non-tabular: column letters as headers

Flags:

  • --sheet / -s (str, default: all) — Target specific sheet
  • --types (bool) — Add column types + null counts
  • --sample (int) — Add N head + N tail rows
  • --stats (bool) — Add numeric/string summaries (implies --types)
  • --full (bool) — Shorthand for --types --sample 3 --stats
  • --no-header (bool) — Treat row 1 as data, use column letters (A, B, C) as headers. For non-tabular sheets like P&L reports and dashboards

Output: sheets[].{name, index, visible, rows, cols, headers, column_map, last_col}, named_ranges, tables

Read

Extract data from sheets/ranges. Default: Polars + fastexcel (fast). With --formulas: openpyxl (slower).

agent-xlsx read <file>                           # First sheet, 100 rows
agent-xlsx read <file> "A1:F50"                  # Range (positional arg)
agent-xlsx read <file> --sheet Sales "B2:G100"   # Sheet + range
agent-xlsx read <file> --limit 500 --offset 100  # Pagination
agent-xlsx read <file> --sort amount --descending # Sorted
agent-xlsx read <file> --formulas                 # Formula strings (slower, openpyxl)
agent-xlsx read <file> "Sheet1!A1:C10,E1:G10"    # Multi-range read
agent-xlsx read <file> "A1:F50" --all-sheets     # Same range across all sheets
agent-xlsx read <file> --no-header                # Non-tabular data
agent-xlsx read <file> --no-compact               # Keep null columns

Flags:

  • --sheet / -s (str, default: first) — Target sheet
  • --limit / -l (int, default: 100) — Max rows (hard cap: 10,000)
  • --offset (int) — Skip first N rows
  • --sort (str) — Sort by column name
  • --descending (bool) — Reverse sort order
  • --formulas (bool) — Return formula strings (openpyxl fallback)
  • --format / -f (str, default: json) — Output format: json, csv
  • --no-header (bool) — Treat row 1 as data, use column letters (A, B, C) as headers
  • --compact/--no-compact (bool, default: on) — Drop fully-null columns to reduce token waste
  • --all-sheets (bool) — Read the same range(s) from every sheet in the workbook

Range is positional: "A1:F50" or "Sheet1!A1:F50". Comma-separated for multi-range: "Sheet1!A1:C10,E1:G10"

Find values across all sheets. Returns cell references with each match.

agent-xlsx search <file> "revenue"               # Substring match, all sheets
agent-xlsx search <file> "rev.*" --regex          # Regex
agent-xlsx search <file> "stripe" --ignore-case   # Case-insensitive
agent-xlsx search <file> "SUM(" --in-formulas     # Search formula strings

Flags:

  • --sheet / -s (str, default: all) — Target specific sheet
  • --regex (bool) — Treat query as regex
  • --ignore-case / -i (bool) — Case-insensitive match
  • --in-formulas (bool) — Search formula strings (openpyxl fallback)
  • --no-header (bool) — Treat row 1 as data, use column letters

Output: matches[].{sheet, cell, column, row, value} — max 25 results. Check truncated field.

--in-formulas output: matches[].{sheet, cell, formula} — different schema, returns the formula string instead of the cell value.

Export

Bulk export sheet data.

agent-xlsx export <file> --format csv              # CSV to stdout
agent-xlsx export <file> --format markdown          # Markdown table
agent-xlsx export <file> --format json              # JSON array
agent-xlsx export <file> --format csv -o out.csv -s Sales

Flags:

  • --sheet / -s (str, default: first) — Target sheet
  • --format / -f (str, default: json) — Format: json, csv, markdown
  • --output / -o (str) — Write to file
  • --no-header (bool) — Treat row 1 as data, use column letters (A, B, C) as headers
  • --compact/--no-compact (bool, default: on) — Drop fully-null columns to reduce token waste

Overview

Structural metadata summary. Uses openpyxl + fastexcel for true dimensions.

agent-xlsx overview <file>
agent-xlsx overview <file> --include-formulas --include-formatting

Flags:

  • --include-formulas (bool) — Add formula summary per sheet
  • --include-formatting (bool) — Add formatting summary

Output: file, sheets[].{name, ...}, named_ranges, named_range_count, has_vba, total_formula_count, total_chart_count

Inspect

Deep metadata inspection. --sheet alone returns everything in one pass.

agent-xlsx inspect <file> --sheet Sales              # Full inspection
agent-xlsx inspect <file> --sheet Sales --range A1:C10  # Scoped
agent-xlsx inspect <file> --names                    # Named ranges
agent-xlsx inspect <file> --charts                   # Chart metadata
agent-xlsx inspect <file> --vba                      # VBA module presence
agent-xlsx inspect <file> --comments                 # Cell comments
agent-xlsx inspect <file> --format "A1" -s Sales     # Cell formatting
agent-xlsx inspect <file> --conditional Sales        # Conditional formatting
agent-xlsx inspect <file> --validation Sales         # Data validation
agent-xlsx inspect <file> --hyperlinks Sales         # Hyperlinks

Flags:

  • --sheet / -s (str) — Full sheet inspection (formulas, merges, tables, charts, comments, conditional formatting, validation, hyperlinks, freeze panes)
  • --range / -r (str) — Scope to range (defaults to first sheet if --sheet not given)
  • --names (bool) — Named ranges only
  • --charts (bool) — Chart metadata only
  • --vba (bool) — Inspect VBA module presence
  • --format / -f (str) — Inspect formatting at a specific cell (e.g. "A1")
  • --comments (bool) — Cell comments only (max 20)
  • --conditional (str) — Conditional formatting rules for a sheet
  • --validation (str) — Data validation rules for sheet
  • --hyperlinks (str) — Hyperlinks for sheet

Format

Read or apply cell formatting.

agent-xlsx format <file> "A1" --read -s Sales         # Read formatting
agent-xlsx format <file> "A1:D1" --font '{"bold": true, "size": 14}'
agent-xlsx format <file> "B2:B100" --number-format "#,##0.00"
agent-xlsx format <file> "A1:D10" --fill '{"color": "FFFF00"}'
agent-xlsx format <file> "A1:D10" --border '{"style": "thin"}'
agent-xlsx format <file> "A1:D10" --copy-from "G1"    # Copy all formatting

Flags:

  • --sheet / -s (str, default: first) — Target sheet
  • --read (bool) — Read formatting instead of writing
  • --font (JSON) — {"bold": true, "size": 14, "color": "FF0000", "name": "Arial"}
  • --fill (JSON) — {"color": "FFFF00", "fill_type": "solid"}
  • --border (JSON) — {"style": "thin", "color": "000000"}
  • --number-format (str) — Number format string (e.g. "#,##0.00")
  • --copy-from (str) — Copy all formatting from this cell
  • --output / -o (str, default: in-place) — Save to new file

Write

Write values or formulas to cells.

agent-xlsx write <file> "A1" "Hello"                              # Single value
agent-xlsx write <file> "A1" "=SUM(B1:B100)" --formula            # Formula
agent-xlsx write <file> "A1:C3" --json '[[1,2,3],[4,5,6],[7,8,9]]' # 2D array
agent-xlsx write <file> "A1" --from-csv import.csv                 # CSV import
agent-xlsx write <file> "A1" "42" --number-format "0.00%"
agent-xlsx write <file> "A1" "Hello" -o new.xlsx -s Sales          # New file

Flags:

  • --sheet / -s (str, default: first) — Target sheet
  • --formula (bool) — Treat value as formula
  • --json (str) — Write 2D JSON array to range
  • --from-csv (str) — Import CSV file starting at cell
  • --number-format (str) — Apply number format
  • --output / -o (str, default: in-place) — Save to new file

VBA macros in .xlsm files are automatically preserved.

Sheet

Manage sheets (create, rename, delete, copy, hide/unhide).

agent-xlsx sheet <file> --list                     # List all sheets
agent-xlsx sheet <file> --create "New Sheet"
agent-xlsx sheet <file> --rename "Old" --new-name "New"
agent-xlsx sheet <file> --delete "Temp"
agent-xlsx sheet <file> --copy "Template" --new-name "Q1"
agent-xlsx sheet <file> --hide "Internal"
agent-xlsx sheet <file> --unhide "Internal"

Flags:

  • --list (bool) — List all sheets
  • --create (str) — Create new sheet
  • --rename (str) — Sheet to rename (pair with --new-name)
  • --new-name (str) — New name for rename/copy
  • --delete (str) — Delete sheet
  • --copy (str) — Copy sheet (pair with --new-name)
  • --hide (str) — Hide sheet
  • --unhide (str) — Unhide sheet
  • --output / -o (str, default: in-place) — Save to new file

Screenshot

HD PNG capture. Auto-fits column widths before capture. Auto-detects engine.

agent-xlsx screenshot <file>                       # All sheets
agent-xlsx screenshot <file> --sheet Sales         # Specific sheet
agent-xlsx screenshot <file> --sheet "Sales,Summary" # Multiple sheets
agent-xlsx screenshot <file> "Sales!A1:F20"        # Range capture (positional)
agent-xlsx screenshot <file> -s Sales -r "A1:F20"  # Range capture (flag)
agent-xlsx screenshot <file> -o ./shots/           # Output directory
agent-xlsx screenshot <file> --engine aspose       # Force engine
agent-xlsx screenshot <file> --dpi 300             # DPI (Aspose/LibreOffice)

Flags:

  • --sheet / -s (str, default: all) — Sheet(s), comma-separated
  • --range / -r (str) — Cell range (e.g. "A1:F20"). Alternative to positional RANGE arg
  • --output / -o (str, default: /tmp/agent-xlsx) — Output directory
  • --engine / -e (str) — Force: excel, aspose, libreoffice
  • --dpi (int, default: 200) — Resolution (Aspose/LibreOffice only)
  • --timeout (int, default: 30) — Seconds (LibreOffice only)
  • --base64 (bool) — Return image data inline in JSON

Range is positional: "Sales!A1:F20" → filename file_Sales_A1-F20.png

Objects

List or export embedded objects (charts, shapes, pictures). Engines: Excel or Aspose.

agent-xlsx objects <file>                          # List all objects
agent-xlsx objects <file> --sheet Sales            # Objects on specific sheet
agent-xlsx objects <file> --export "Chart 1"       # Export chart as PNG
agent-xlsx objects <file> --engine aspose          # Force Aspose

Flags:

  • --sheet / -s (str, default: all) — Target sheet
  • --export / -e (str) — Export named chart as PNG
  • --output / -o (str, default: /tmp/agent-xlsx) — Output path
  • --engine (str) — Force: excel, aspose

Recalc

Recalculate formulas or scan for errors. Auto-detects engine.

agent-xlsx recalc <file> --check-only              # Scan for errors (no engine needed)
agent-xlsx recalc <file>                           # Full recalculation
agent-xlsx recalc <file> --engine aspose           # Force Aspose
agent-xlsx recalc <file> --timeout 120             # Timeout (LibreOffice only)

Flags:

  • --check-only (bool) — Scan for errors without recalculating (no engine needed)
  • --engine / -e (str) — Force: excel, aspose, libreoffice
  • --timeout (int, default: 60) — Seconds (LibreOffice only)

--check-only finds: #REF!, #DIV/0!, #NAME?, #NULL!, #N/A, #VALUE!, #NUM!

VBA

VBA macro analysis and execution. oletools for read/analysis (cross-platform), xlwings for execution (Excel required).

agent-xlsx vba <file> --list                       # List modules + security summary
agent-xlsx vba <file> --read ModuleName            # Read module code
agent-xlsx vba <file> --read-all                   # All modules (max 500 lines each)
agent-xlsx vba <file> --security                   # Full security analysis
agent-xlsx vba <file> --run "Module1.MyMacro"      # Execute (requires Excel)
agent-xlsx vba <file> --run "MyMacro" --args '[1]' # With arguments

Flags:

  • --list (bool) — List modules + security summary
  • --read (str) — Read specific module code
  • --read-all (bool) — Read all modules (max 500 lines each)
  • --security (bool) — Full analysis (auto_execute, suspicious keywords, IOCs, risk_level)
  • --run (str) — Execute macro (Excel required). Format: "Module1.MacroName"
  • --args (JSON) — Arguments for macro: '[1, "hello"]'
  • --save (bool) — Save workbook after execution

License

Manage Aspose.Cells licence for watermark-free rendering.

agent-xlsx license --status                        # Check install + licence status
agent-xlsx license --set /path/to/Aspose.Cells.lic # Save licence path
agent-xlsx license --clear                         # Remove saved licence

Flags:

  • --status (bool) — Check Aspose install + licence status
  • --set (str) — Save licence file path to config (~/.agent-xlsx/config.json)
  • --clear (bool) — Remove saved licence path

Env vars: ASPOSE_LICENSE_PATH (file path) or ASPOSE_LICENSE_DATA (base64-encoded .lic content for CI/CD). Priority: env var → config file.