Skip to main content
Search file contents in the session image using server-side ripgrep, without spawning a sandbox.

​
Examples

​
Output

The default format prints classic PATH:LINE:TEXT lines, one per match – the same shape as running grep -rn locally:
With -A/-B/-C, context lines use - instead of : and a -- line separates output groups that aren’t directly adjacent – the same convention GNU grep and ripgrep use:
Structured formats (-o json, -o csv, -o table, …) instead get one row per match/context line with the columns path, line_number, absolute_offset, line_bytes, line_text, type (match or context).

​
Help output

$ contree grep —help
usage: contree grep [-h] [—glob GLOB] [—max-count MAX_COUNT] [—max-total MAX_TOTAL]
                    [—case {sensitive,insensitive,smart}] [-B NUM] [-A NUM] [-C NUM] [—raw]
                    pattern [path …]

Search file contents in the session image.

Uses the /inspect/ API (server-side ripgrep) to search file contents
without spawning an instance. Defaults to the session working directory
(set via `cd`) when PATH is omitted — pass `/` explicitly to search the
whole image. PATH may be repeated to search multiple roots in one call.

positional arguments:
  pattern               Regex pattern to search for (Rust regex syntax)
  path                  File(s)/directory(ies) inside image (defaults to session cwd); may be
                        repeated to search multiple roots

options:
  -h, —help            show this help message and exit
  —glob GLOB           Restrict search to files matching this glob (e.g. ‘*.py’)
  —max-count MAX_COUNT
                        Stop after this many matches per file
  —max-total MAX_TOTAL
                        Stop after this many matches total (server default: 1000)
  —case {sensitive,insensitive,smart}
                        Case sensitivity (default: sensitive)
  -B, —before-context, —before NUM
                        Show NUM lines of context before each match (max 50)
  -A, —after-context, —after NUM
                        Show NUM lines of context after each match (max 50)
  -C, —context NUM     Show NUM lines of context before and after (overridden by -A/-B)
  —raw                 Print raw JSON (preserves submatches/patterns/truncated)

for coding agents:
  read-only command (inspect API, no instance spawn)
  defaults to session cwd when PATH is omitted; pass / to search whole image
  exit code 1 means zero matches (like POSIX grep), not an error
  exit code 2 means the search was truncated before finding anything —
  inconclusive, not confirmed zero matches
  default format prints classic PATH:LINE:TEXT; use -o json/csv/… for rows
  use —raw to preserve submatches/patterns/truncated as JSON
  -A/-B/—context add ripgrep-side context lines (server-computed, not local)

agent note:
  Before using this command in an automated workflow, read:
    contree agent

​
Behavior

grep searches file contents directly in the image filesystem – no sandbox is started. Matching is powered by ripgrep with Rust regex syntax and linear-time matching; symlinks are never followed, hidden files are searched, and binary files (containing a NUL byte) are skipped. When PATH is omitted, the search defaults to the session working directory (set via cd), consistent with ls - List files in the image and cat - Show file content from the image. Pass / explicitly to search the whole image. -B/--before-context/--before, -A/--after-context/--after, and -C/--context request extra lines of context around each match (server -side, up to 50 lines each way) – -C sets both directions unless overridden by an explicit -A/-B. This mirrors GNU grep/ripgrep’s own flags; -C is a deliberate one-off exception to this CLI’s usual uniqueness rule for short flags (-C is --cwd everywhere else). Nested match detail (submatches) is dropped from structured output; pass --raw to get the full JSON response, including submatches, the searched patterns, and the truncated flag – useful for jq pipelines. The command exits with status 1 when no matches are found (like POSIX grep), so it composes in shell conditionals:
Exit status 2 is different from 1: it means the search was truncated (max_total/the server deadline was hit) before finding anything at all, which is inconclusive rather than a confirmed zero-match result. A truncated search that still found at least one match exits 0/none as usual – truncated only affects the exit code when combined with zero matches.

​
See also