← Back to Home

api-reference / cli

CLI Reference

Complete reference for gnaw's command-line interface.

Basic Syntax

gnaw [OPTIONS] PATTERN [FILE...]
gnaw [OPTIONS] --chat "NATURAL_LANGUAGE_QUERY"
gnaw agent COMMAND [OPTIONS]

Global Options

| Option | Description | Default | |--------|-------------|---------| | -h, --help | Show help information | - | | -V, --version | Show version information | - | | --config FILE | Use configuration file | gnaw.toml | | --no-config | Disable configuration file | - | | --verbose | Enable verbose output | - | | --quiet | Suppress non-error output | - |

Search Options

Pattern Matching

| Option | Description | Example | |--------|-------------|---------| | -e, --regexp PATTERN | Pattern to search for | gnaw -e "ERROR" file.txt | | -F, --fixed | Treat pattern as literal string | gnaw -F "exact text" file.txt | | -E, --extended | Use extended regex | gnaw -E "ERROR\|WARN" file.txt | | -i, --ignore-case | Case insensitive search | gnaw -i "error" file.txt |

Search Scope

| Option | Description | Example | |--------|-------------|---------| | -r, --recursive | Search directories recursively | gnaw -r "pattern" ./logs/ | | --no-ignore | Disable ignore rules | gnaw --no-ignore "pattern" . | | --ignore-file FILE | Use custom ignore file | gnaw --ignore-file .customignore "pattern" . |

Context Options

| Option | Description | Example | |--------|-------------|---------| | -A, --after-context NUM | Show NUM lines after match | gnaw -A 3 "ERROR" file.txt | | -B, --before-context NUM | Show NUM lines before match | gnaw -B 2 "ERROR" file.txt | | -C, --context NUM | Show NUM lines before and after | gnaw -C 2 "ERROR" file.txt |

Output Options

| Option | Description | Example | |--------|-------------|---------| | -c, --count | Show count of matches | gnaw -c "pattern" file.txt | | -l, --files-with-matches | Show only filenames with matches | gnaw -l "pattern" ./logs/ | | -L, --files-without-matches | Show only filenames without matches | gnaw -L "pattern" ./logs/ | | -n, --line-number | Show line numbers | gnaw -n "pattern" file.txt | | -H, --with-filename | Always show filename | gnaw -H "pattern" file.txt | | -o, --only-matching | Show only matching part | gnaw -o "pattern" file.txt |

Advanced Options

| Option | Description | Example | |--------|-------------|---------| | -v, --invert-match | Invert match (show non-matching lines) | gnaw -v "pattern" file.txt | | --json | Output in JSON format | gnaw --json "pattern" file.txt | | --raw | Output raw count (with -c) | gnaw --raw -c "pattern" file.txt | | --stream | Stream output as found | gnaw --stream "pattern" file.txt |

Chat Mode

Natural Language Search

gnaw --chat "NATURAL_LANGUAGE_QUERY" [OPTIONS]

Options:

  • --dry-run: Show generated command without executing
  • --json: Output in JSON format
  • --stream: Stream results as found

Examples:

gnaw --chat "Find all error messages in log files"
gnaw --chat "Show me lines with WARNING in server.log" --dry-run
gnaw --chat "Find authentication functions" --json

Agent Mode

Index Management

gnaw agent index COMMAND [OPTIONS]

Commands:

  • build: Build code index for semantic search
  • update: Update existing index
  • status: Show index status and statistics
  • clean: Remove index files

Options:

  • --target-dir DIR: Specify target directory
  • --force: Force rebuild even if index exists

Examples:

gnaw agent index build
gnaw agent index build --target-dir /path/to/code
gnaw agent index status
gnaw agent index update

Semantic Search

gnaw agent ask QUERY [OPTIONS]

Options:

  • --json: Output in JSON format
  • --type TYPES: Filter by file types (comma-separated)
  • --dir DIR: Filter by directory
  • --limit NUM: Maximum number of results (default: 10)
  • --target-dir DIR: Use custom index directory

Examples:

gnaw agent ask "authentication functions"
gnaw agent ask "error handling" --type rs,go,js
gnaw agent ask "database queries" --dir src/db --json
gnaw agent ask "API endpoints" --limit 5

Configuration

Configuration File

gnaw uses gnaw.toml for configuration:

# gnaw.toml
chunk_size = 100
output_format = "ascii_box"
color = true
match_color = "cyan"
io_chunk_size_bytes = 8388608

[tuning]
tiny = "64 KiB"
small = "8.6 MiB"
medium = "256 MiB"
large = "2 GiB"

[regex.simple]
size_limit_mb = 200
dfa_size_limit_mb = 200
nest_limit = 250

[regex.complex]
size_limit_mb = 100
dfa_size_limit_mb = 100
nest_limit = 200

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | GNAW_CONFIG | Configuration file path | gnaw.toml | | RUST_LOG | Log level | error | | RAYON_NUM_THREADS | Number of threads | 0 (all cores) |

Exit Codes

| Code | Description | |------|-------------| | 0 | Success | | 1 | No matches found | | 2 | Error occurred | | 3 | Invalid arguments | | 4 | File not found | | 5 | Permission denied |

Examples

Basic Search

# Simple pattern search
gnaw "ERROR" test.log

# Case insensitive search
gnaw -i "error" test.log

# Show line numbers
gnaw -n "ERROR" test.log

Advanced Search

# Recursive search with context
gnaw -r -C 2 "ERROR" ./logs/

# Multiple patterns
gnaw -e "ERROR" -e "WARN" test.log

# Fixed string search
gnaw -F "exact text" file.txt

Output Formats

# JSON output
gnaw --json "ERROR" test.log

# Count only
gnaw -c "ERROR" test.log

# Files with matches
gnaw -l "ERROR" ./logs/

Agent Mode

# Build index
gnaw agent index build

# Semantic search
gnaw agent ask "authentication functions"

# Filtered search
gnaw agent ask "error handling" --type rs --dir src/

Troubleshooting

- Check file permissions - Use `sudo` if necessary - Verify directory access - Check if files are being ignored - Verify pattern syntax - Try case-insensitive search - Use more specific patterns - Limit search scope - Check configuration Use `gnaw --help` for detailed help information and `gnaw --version` to check your installation.