> ## 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 a container image using ripgrep, without spawning a VM.

## Overview

`grep` runs a regex content search over an image’s persisted root filesystem, powered by ripgrep on the backend. Use it to find where a config key, symbol, or string lives before running commands — it’s instant and free, unlike `run("grep ...")` which needs a microVM.

Symlinks are never followed, hidden files are searched, `.gitignore`-style files inside the image are ignored, and binary files (containing a NUL byte) are skipped.

## Parameters

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `image` | string | Yes | - | Image UUID or `tag:name` |
| `pattern` | string | Yes | - | Rust-flavored regex to search for |
| `path` | string | No | rootfs root | File or directory to search inside the image |
| `glob` | string | No | - | Glob to filter files (ripgrep `-g` semantics, `!` negates) |
| `max_count` | integer | No | - | Maximum matches per file |
| `max_total` | integer | No | 1000 | Maximum total matches across all files |
| `case` | string | No | - | `sensitive`, `insensitive`, or `smart` |

## Returns

| Field | Type | Description |
| - | - | - |
| `path` | string | The path inside the image that was searched |
| `patterns` | array | The patterns that were searched for |
| `truncated` | boolean | True when `max_total` or the search deadline stopped the search early |
| `matches` | array | List of matching lines |

### Match Fields

| Field | Type | Description |
| - | - | - |
| `path` | string | File path relative to the image rootfs |
| `line_number` | integer | 1-based line number of the match |
| `line_text` | string | The matching line |

## Cost

**Free** - No VM spawned. Searches directly over the image filesystem.

## Examples

### Find a Config Setting

```json theme={null}
{
  "tool": "grep",
  "args": {
    "image": "abc123-def456",
    "pattern": "^PermitRootLogin",
    "path": "/etc/ssh"
  }
}
```

### Scope by File Type

```json theme={null}
{
  "tool": "grep",
  "args": {
    "image": "tag:python:3.11-slim",
    "pattern": "TODO",
    "glob": "*.py"
  }
}
```

### Case-Insensitive Search

```json theme={null}
{
  "tool": "grep",
  "args": {
    "image": "img-uuid",
    "pattern": "error",
    "case": "insensitive"
  }
}
```

## Best Practices

* **Prefer over `run("grep ...")`** - `grep` is instant and free
* **Narrow with `path` and `glob`** - avoid scanning the whole rootfs when you know roughly where to look
* **`pattern` is a regex, not a literal string** - escape special characters if you want an exact match
* **Combine with `list_files`** - list a directory first, then grep the files you find interesting

## See Also

* [list\_files](./list_files) - List files and directories without a VM
* [read\_file](./read_file) - Read a single file’s full contents without a VM
* [run](./run) - Execute commands (spawns VM), e.g. for tools ripgrep can’t replace