> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/rtk-ai/rtk/llms.txt
> Use this file to discover all available pages before exploring further.

# rtk grep

> Compact search with grouped results

## Overview

Searches files using ripgrep (or grep fallback) with token-optimized output grouped by file. Automatically truncates long lines and limits results.

## Syntax

```bash theme={null}
rtk grep [OPTIONS] <PATTERN> [PATH]
```

## Arguments

**PATTERN** `string` *required*

Search pattern (regex supported). BRE alternation `\|` auto-converted to PCRE `|`.

**PATH** `string` (default: .)

Directory to search (recursive by default)

## Options

**-l, --max-len** `number` (default: 80)

Maximum line length in results. Long lines truncated with `...` around match.

**-m, --max** `number` (default: 50)

Maximum total results to show across all files.

**-c, --context-only** `flag`

Show only 20 chars before/after match instead of full line.

**-t, --file-type** `string`

Filter by file type: `ts`, `py`, `rust`, `js`, etc. (ripgrep type names)

**-n, --line-numbers** `flag`

Show line numbers (always enabled, accepted for grep/rg compatibility)

### Pass-through Arguments

Additional ripgrep flags supported via trailing args:

* `-i` - Case-insensitive search
* `-w` - Match whole words
* `-A N` - Show N lines after match
* `-B N` - Show N lines before match
* `--glob PATTERN` - Include/exclude files by glob

## Output Format

```
🔍 12 in 3F:

📄 src/main.rs (5):
   42: pub fn run_grep(pattern: &str) -> Result<()> {
   67:     let matches = grep_impl(pattern)?;
  ... +3 more

📄 src/lib.rs (4):
   12: // grep helper function
   23:     pattern.to_lowercase()
  ... +2 more

... +1 more file
```

**Format breakdown:**

* Header: `🔍 12 in 3F` (12 matches in 3 files)
* Per-file section with match count
* Line numbers auto-enabled
* Shows first 10 matches per file
* Truncates at `--max` total results

## Token Savings

**75% reduction** - grouping by file and line truncation

```bash Example: Basic search theme={null}
rtk grep "TODO" src
# Find all TODO comments in src/
```

```bash Example: Type filter theme={null}
rtk grep -t ts "useState" .
# Search only TypeScript files
```

```bash Example: Context only theme={null}
rtk grep -c "error" logs/
# Show only ±20 chars around "error"
```

```bash Example: With ripgrep flags theme={null}
rtk grep -i "fixme" . -A 2 --glob '*.rs'
# Case-insensitive, 2 lines after, Rust files only
```

```bash Example: Regex with alternation theme={null}
rtk grep "fn foo\|pub.*bar" src
# Auto-converts BRE \| to PCRE |
```

## Special Behaviors

### BRE to PCRE Conversion

RTK auto-converts Basic Regular Expression alternation `\|` to Perl-Compatible `|` for ripgrep compatibility:

```bash theme={null}
rtk grep "error\|warning"  # Works correctly
```

### Recursive by Default

Unlike traditional grep, RTK searches recursively. The `-r` flag is ignored (ripgrep is always recursive).

### Smart Truncation

Long lines are truncated intelligently:

* Match is centered in output
* `...prefix...match...suffix...` format
* Respects `--max-len` character limit
* Handles multibyte characters (emoji, Unicode) correctly

## Exit Codes

* `0` - Matches found
* `1` - No matches found
* `2` - Error (bad regex, missing directory)

## Related Commands

* `rtk read` - View file contents
* `rtk find` - Find files by name
* `rtk ls` - List directory contents


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.