xlgrep 0.5.0

Usage • Key features • Installation • AI agents • Development

xlgrep is grep for spreadsheets: search cell values and formulas
across folders of .xlsx, .xlsm, .xlsb, .xls and .ods files. Read-only.

Usage

xlgrep smith -i                  # current folder, recursive, case-insensitive
xlgrep "O'Brien" C:\dir -F       # literal text
xlgrep smith -w                  # whole word (-wF "C++" works too)
xlgrep smith -x                  # whole cell
xlgrep smith --row               # print each matching row in full
xlgrep smith --row --header      # ...with each value labeled by its column's header in row 1
xlgrep smith --sheet Contacts    # only that sheet
xlgrep VLOOKUP --formulas -l     # workbooks whose formulas use VLOOKUP
xlgrep smith -c                  # hit count per file (rows with --row)
xlgrep smith -m 5                # stop each file after 5 hits
xlgrep smith --json --row        # JSON Lines for scripts and agents
xlgrep smith --json | head -50   # first 50 hits overall; the search stops early

Run xlgrep --help for the full option list.

Key features

Click to learn more.

Installation

Windows, with Scoop:

scoop bucket add xlgrep https://github.com/DavisMcCracken/xlgrep
scoop install xlgrep

Windows, macOS or Linux, from PyPI with uv or pipx. The wheel holds the same binary; there's no Python code.

uv tool install xlgrep        # or: pipx install xlgrep

uvx xlgrep … runs it without installing.

Or download the zip (Windows) or tar.gz (Linux x86_64/ARM, static, any distro) from Releases, unpack, and put xlgrep on your PATH. Each release has a SHA256SUMS file to check the download.

Or with Cargo:

cargo install xlgrep --locked

Using with AI agents

Paste this into your agent instructions (AGENTS.md, CLAUDE.md, …):

To search or read .xlsx/.xlsm/.xlsb/.xls/.ods files, use `xlgrep` instead of writing
openpyxl/pandas scripts (if `xlgrep --version` fails, `uvx xlgrep …` runs it). Use `--json` when
parsing output: `{"file","sheet","cell","value"}` per hit; add `--row` for the whole matching row
and `--header` to label values with their column's header from row 1 (`--header=3` if the headers
are in row 3; stderr suggests the row when row 1 looks like a title). Keep output small: `-m 20`
per file, `| head -N` overall; `-l` (matching files) and `-c` (hits per file) print plain lines,
not JSON.
Examples: `xlgrep "smith" -i --json -m 20`, `xlgrep VLOOKUP --formulas -l`,
`xlgrep . book.xlsx --sheet Sheet1 --json | head -100` (dump a sheet's non-empty cells).
Values are raw: search `51200`, not `$51,200.00`, and `0.15`, not `15%`; dates are `2024-03-05`.
Add `-x` for an exact value (`51200` alone also matches `151200`). .csv/.tsv files aren't
searched (stderr counts them): grep those separately.
Exit 1 = no match; exit 2 = something couldn't be searched: read stderr before concluding a value
isn't there (it also lists skipped OneDrive online-only files, which don't change the exit code).
PowerShell's `-Command` reports exit 2 as 1, so read stderr there too.
Don't pass `--download` (it downloads OneDrive online-only files) without asking.

Development

Build and run

cargo run --release -- <xlgrep args>

Run all tests

cargo test

On Windows without admin/Visual Studio, use the GNU toolchain: scoop install rustup-gnu.

Releasing

Bump version in Cargo.toml, commit, then git tag v0.2.0 && git push --tags. The release workflow checks the tag matches Cargo.toml, builds and tests, publishes the binaries with SHA256SUMS, updates the Scoop manifest (bucket/xlgrep.json) and publishes to crates.io and PyPI (wheels built with maturin, holding the same binary). Running it by hand from the Actions tab builds and tests without publishing.

License

MIT or Apache-2.0, at your option.