> ## Documentation Index > Fetch the complete documentation index at: https://docs.tokenfactory.nebius.com/llms.txt > Use this file to discover all available pages before exploring further. # grep - Search file contents in the image Search file contents in the session image using server-side ripgrep, without spawning a sandbox. ## Examples ```bash theme={null} # Search the session cwd for a pattern contree grep TODO # Search a specific file or directory contree grep "^PermitRootLogin" /etc/ssh/sshd_config # Search the whole image (PATH omitted defaults to cwd; pass / for the root) contree grep TODO / # Restrict to a glob, limit match count, case-insensitive contree grep --glob '*.py' --max-count 5 --case insensitive def /app # 2 lines of context before and after each match, like grep -C 2 contree grep -C 2 ERROR /var/log/app.log # asymmetric context, like grep -A/-B (--after/--before also work) contree grep -B 1 -A 3 ERROR /var/log/app.log # JSON output for scripting (one row per match) contree -o json grep TODO /app ``` ## Output The default format prints classic `PATH:LINE:TEXT` lines, one per match – the same shape as running `grep -rn` locally: ``` /etc/hosts:1:127.0.0.1 localhost /etc/hosts:2:255.255.255.255 broadcasthost ``` 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: ``` /var/log/app.log-4-starting request /var/log/app.log:5:ERROR: connection refused /var/log/app.log-6-retrying -- /var/log/app.log-40-starting request /var/log/app.log:41:ERROR: timeout /var/log/app.log-42-giving up ``` 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](./ls) and [cat - Show file content from the image](./cat). 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: ```bash theme={null} if contree grep ERROR /var/log/app.log > /dev/null; then echo "found errors" fi ``` 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 * [ls - List files in the image](./ls) – list files before searching * [cat - Show file content from the image](./cat) – view a single file’s full contents