Skip to content
agent-xlsx

agent-xlsx

Excel file CLI built for AI agents. Structured JSON output optimised for context efficiency. Polars + fastexcel for speed, openpyxl for metadata, three rendering engines for screenshots.

Run instantly (zero install)

uvx agent-xlsx probe spreadsheet.xlsx

Or install it

uv tool install agent-xlsx   # or: pip install agent-xlsx
agent-xlsx probe spreadsheet.xlsx

Agent Skill

Give your AI agent built-in knowledge of agent-xlsx commands and workflows by installing it as a skill:

npx skills add apetta/agent-xlsx

Works with Claude Code, Cursor, Gemini CLI, and 20+ other agents. Browse and install from skills.sh.

Features

  • Agent-first — Structured JSON to stdout, optimised for AI context windows. Consistent schema, truncation flags, and structured error codes
  • Fast — Polars + fastexcel (Rust-based), 7-10x faster than openpyxl for data reads. Scales to 100K+ rows
  • Complete — 14 commands for reading, writing, searching, screenshots, VBA, and more
  • Three rendering engines — xlwings (Excel, highest fidelity), Aspose.Cells (cross-platform, headless), LibreOffice (free fallback). See Backends
  • Non-tabular support — --no-header mode for P&L reports, dashboards, and sheets where row 1 isn't a header
  • Compact output — Automatically drops null columns to minimise token waste
  • Cross-platform — macOS, Linux, Windows
  • 5 formats — .xlsx, .xlsm, .xlsb, .xls, .ods. See Formats

Example

# Profile a spreadsheet
agent-xlsx probe data.xlsx --full

# Output includes column_map for building ranges:
# {"column_map": {"user_id": "A", "amount": "E"}, "last_col": "W"}

# Read specific data
agent-xlsx read data.xlsx "A1:F50" --sort amount --descending

# Search across all sheets
agent-xlsx search data.xlsx "overdue" --ignore-case

# Take HD screenshots
agent-xlsx screenshot data.xlsx --sheet Sales