Skip to content
agent-xlsx

Changelog

V0.7.0 (FEBRUARY 2026)

Alignment & batch formatting, multi-range batching, search optimization, and token reduction.

  • Added alignment support (--horizontal, --vertical, --wrap-text) and batch formatting (--batch/--batch-file) for applying multiple styles in a single call
  • Optimised multi-range reads — batches via a single file open with in-memory slicing instead of N separate readers, with automatic header resolution
  • Improved search performance on large files (>10 MB) — full-load-then-slice heuristic avoids slow sequential skip_rows in fastexcel/calamine
  • Added --no-meta global flag to suppress _data_origin and file_size_human fields from output
  • Added --brief probe mode for condensed column profiles and --precision flag for float rounding
  • Detects uncached formula cells and surfaces has_uncached_formulas hint so agents don't misinterpret empty cached values as missing data
  • Truncates long strings in probe samples/summaries and classifies free-text columns compactly to prevent token explosions on wide sheets
  • Relativized output_file paths in write/format responses
  • Updated skill and README documentation for new flags

V0.6.0 (FEBRUARY 2026)

Format shorthands, structured error handling, and reliability fixes.

  • Added format shorthand flags (--bold, --italic, --font-size, --font-color, --fill-color) and multi-range format support in a single call
  • Added write --value for shell-safe negative numbers and --from-json for file-based 2D array input
  • Added probe --head-cols to limit column profiling on wide files
  • Added structured CLI error handling — emits JSON with actionable suggestion fields instead of raw tracebacks
  • Fixed EmptyCell crash in --formulas mode, multi-range --output overwrites in format, and OOB column range crashes in read
  • Fixed openpyxl 3.1+ compatibility — replaced private _cf_rules and _hyperlinks accessors with stable public APIs
  • Integrated ty type checker into CI and pre-commit hooks
  • Added ~3,700 lines of new tests across 13 test modules

V0.5.1 (FEBRUARY 2026)

Bug fixes from real-world agent pipeline testing.

  • Fixed --formula with --json and --from-csv — no longer prepends = to all strings in batch mode. Plain text stays plain; only strings starting with = are written as formulas. Single-cell --formula behavior unchanged
  • Fixed --columns by header name when combined with --range — row-1 headers are now resolved even in range-scoped searches (both Polars and openpyxl paths)
  • Fixed --headers on multi-range reads — column letters are now resolved to row-1 header names with per-sheet caching, matching single-range behavior
  • Fixed resolve_column_letters() to prioritise header name lookup over column letter matching — prevents purely alphabetic header names (e.g. "Formula") from being misinterpreted as column letters
  • Updated --formula description in command reference to reflect batch vs single-cell semantics
  • Added 6 regression tests for mixed formula/text writes, header name + range search, and multi-range header resolution

V0.5.0 (FEBRUARY 2026)

Search precision, write auto-create, and developer experience.

  • Added --columns / -c flag to search — filter results to specific columns by letter (A,B,C) or header name ("Indicator Name")
  • Added --limit / -l flag to search — cap result count (default 25, max 1000)
  • Added --range flag to search — restrict search to a cell range (e.g. A1:D100 or Sheet!A1:D100). Composes with --columns and --limit
  • Added --headers flag to read — resolves column letters to row-1 header names in range reads, with column_map in output
  • Added write auto-create — writing to a non-existent .xlsx or .xlsm file now creates it automatically. Emits "created": true in output
  • Extended --formula flag in write to work with --json and --from-csv (previously single-cell only). Adds = prefix to strings missing it
  • Added write size guard — --output on files larger than 20 MB fails fast with FILE_TOO_LARGE; in-place writes on large files emit a warning
  • Added file_size_human field to probe, read, and search output — human-readable file size for agent timeout calibration
  • Added INVALID_COLUMN and FILE_TOO_LARGE structured error codes
  • Added pre-commit hooks — ruff check --fix and ruff format on commit, full pytest suite on push
  • Added ruff format --check to CI publish workflow
  • Added 37 tests across test_write.py, test_search.py, and test_read.py

V0.4.0 (FEBRUARY 2026)

Security hardening, untrusted-data tagging, and engine unification.

  • Added _data_origin: untrusted_spreadsheet field to all structured JSON responses — provides per-call provenance context for agent consumers across read, search, probe, overview, inspect, format --read, export --format json, and vba
  • Added --json-envelope flag to export — wraps CSV and Markdown stdout in a JSON envelope with _data_origin for agent pipelines that need provenance on all output formats
  • Added automatic VBA security pre-check before every macro execution — macros with risk_level=high are blocked and raise MacroBlockedError; use --allow-risky to override when the file source is explicitly trusted
  • Added extension gate to vba --run — macro execution now requires .xlsm or .xlsb; plain .xlsx files are rejected with a structured error
  • Added macro name validation to vba --run — rejects names containing path separators or shell meta-characters
  • Added XXE protection — defusedxml.defuse_stdlib() is activated at import time, hardening all stdlib XML parsers used by openpyxl and oletools against entity expansion and DTD retrieval attacks
  • Fixed chart export filename sanitisation — strips path separators and .. sequences to prevent path traversal via crafted chart names
  • Fixed copy_formatting() missing the writable-extension guard (now consistent with write_cells() and apply_formatting())
  • Fixed ASPOSE_LICENSE_DATA warning — now emitted on env-var presence, even when ASPOSE_LICENSE_PATH takes precedence, since the env var remains visible in process listings
  • Unified engine auto-detection order across objects, recalc, and screenshot — priority is now consistently Aspose → Excel → LibreOffice via a shared resolve_engine utility
  • Added 26 security regression tests covering data-origin tagging, VBA gates, and credential warning behaviour
  • Added lint-and-test CI gate before PyPI publish; pinned all GitHub Actions to immutable commit SHAs

V0.3.0 (FEBRUARY 2026)

Date handling overhaul, docs site, and reliability fixes.

  • Added documentation site with full command reference, backend guide, and changelog
  • Overhauled date handling — index-based detection now works correctly in --no-header mode across read, search, export, and probe. Midnight datetimes normalised to date-only strings
  • Added INVALID_REGEX structured error for malformed regex patterns in search --regex (including Rust regex engine incompatibilities)
  • Further optimised print area handling in LibreOffice _prepare_sheet_for_export for better PDF export
  • Added save-path guard in format and sheet commands — non-writable extensions now fall back to .xlsx instead of silently saving OOXML content with the original extension
  • Updated skill and command reference docs for output format clarity (--format csv|markdown), --in-formulas output schema, and engine availability per command

V0.2.0 (FEBRUARY 2026)

Non-tabular data support, multi-range reads, and compact output.

  • Added --no-header flag to probe, read, search, and export for non-tabular sheets (P&L reports, dashboards). Treats row 1 as data and uses column letters (A, B, C) as headers
  • Added --compact/--no-compact mode to read and export (default: on). Drops fully-null columns to reduce token waste
  • Added --all-sheets flag to read for reading the same range(s) from every sheet
  • Added multi-range read support — comma-separated ranges like "Sheet1!A1:C10,E1:G10"
  • Added --range / -r option flag to screenshot (alternative to positional RANGE arg)
  • Added --vba and --format / -f flags to inspect
  • Changed auto-detection priority — Aspose is now checked first for screenshot and recalc (was Excel first)
  • Added shell-escaped cell reference normalisation for zsh compatibility (\! in ranges)
  • Fixed xlwings screenshot transparency — PNGs are now opaque (flattened onto white background)
  • Enhanced LibreOffice multi-page PDF rendering and print area optimisation
  • Improved formula detection in compact mode
  • Added aspose-cells-python as a direct dependency

V0.1.1 (FEBRUARY 2026)

CLI polish release.

  • Added -h / --help flag support across all commands
  • Added --version / -V flag to display the installed version
  • Removed shell completion clutter from help output
  • Fixed -o flag conflict on read --offset
  • Fixed double period in help text descriptions

V0.1.0 (FEBRUARY 2026)

Initial release.

  • 14 commands: probe, overview, inspect, read, search, write, sheet, format, export, screenshot, objects, recalc, vba, license
  • 5 adapters: Polars + fastexcel for data reads, openpyxl for metadata and writes, xlwings for Excel rendering, Aspose.Cells for cross-platform rendering, LibreOffice for free rendering
  • Polars + fastexcel for fast data reads (7-10x faster than openpyxl)
  • openpyxl for metadata inspection and write operations
  • xlwings / Aspose / LibreOffice for screenshots, objects, and recalculation
  • oletools for VBA macro inspection and extraction
  • Structured JSON output to stdout, optimised for AI context windows
  • Auto date detection — converts Excel serial numbers to ISO 8601 strings
  • 5 formats — .xlsx, .xlsm, .xlsb, .xls, .ods
  • Agent Skill support — works with Claude Code, Cursor, and other AI agents via skill files