OptionalcontextAnnotate each match with the block it sits in, and group the listing by block — the 2-D
answer to rg -C.
±N lines is meaningless in a grid; the question context answers is "what is this thing
part of?", and the honest unit for that is the uniform region containing the match — see
GrepContext. true means 'contentful'. A numeric value is rejected rather than
reinterpreted: -C 3 means something else in every other grep, and accepting it while
meaning "enclosing block" would be a silent divergence.
OptionalfieldsWhich layers to search.
GREP_FIELDS_DEFAULT —
['display', 'formula', 'comment', 'shape', 'chart', 'name']
OptionalfixedTreat pattern as a literal string — rg -F.
false — the pattern is a regex by default, because that is what the name
grep means everywhere an agent learned it (POSIX grep and rg both default to regex). A
wildcard default was tried and rejected: agents type \d+ by reflex, wildcards literalize
it, and the result is a silent zero-hit miss. Excel's ?/* wildcards live in the UI find
dialog, where Excel users live.
OptionalhiddenSearch hidden rows, columns and hidden sheets — rg --hidden.
OptionalignoreCase-insensitive matching.
OptionalinvertInvert the match — report cells and objects where no requested field matched (rg -v).
OptionalmaxStop after this many matches — cells and objects together. Truncation is always reported, never silent.
200 — a grep result returns into a context window, not a terminal stream,
so unbounded output is a cost the caller did not ask for. 0 removes the cap.
Counts cells and objects, not match rows — a cell matching in two fields is one unit of
budget, and so is a chart matching in its title and an axis.
The search looks one match past the cap, so a result that ends exactly at maxCount is
only reported truncated when a further match actually exists.
OptionaloutputThe pattern to search for — a regular expression, as in every grep.
Full JS RegExp semantics (lookaround and backreferences work — more than rg's default
engine). Literal search is GrepArgs.fixedStrings.
OptionalscopeWhere to search: a sheet name (globs allowed — Q*), a sheet-qualified range
(Sheet1!A1:D9), or a bare range applied to every sheet.
Resolution order is fixed and documented rather than sniffed: a ! splits sheet from
range; otherwise an exact sheet-name match wins; otherwise a glob (*/?) matches sheet
names; otherwise it is a range on every sheet. A bare range cannot resolve against an
"active sheet" — a stateless invocation has none, and inventing one would make the same
command mean different things in different surfaces.
Naming a hidden sheet (exactly or via a glob-free match) searches it — an explicit name
is an explicit request, the same way rg searches a hidden file you name.
OptionalwordRequire the match to fall on word boundaries.
Boundaries are grep's, not \b's: a pattern that starts or ends on a non-word character
($1,234, 4%, #N/A — spreadsheet text is full of them) still matches at text edges,
exactly as rg -w treats line edges. Implemented as (?<!\w)…(?!\w), which coincides
with \b for word-bounded patterns and stays correct for the rest.
Arguments to grep.
Remarks
Shaped after ripgrep rather than after anything novel — args, defaults and vocabulary are already pretrained, and every novel idiom is paid for in error loops.