← Back to Home

quick-start

Quick Start

Get up and running with gnaw in minutes. This guide covers the most common use cases and commands.

Installation

Homebrew (Recommended for macOS)

brew tap 10printhello/gnaw
brew install gnaw

From Source

git clone https://github.com/10printhello/gnaw.git
cd gnaw
cargo build --release
sudo mv target/release/gnaw /usr/local/bin/

Basic Usage

Traditional Grep Mode

Search for a pattern in a file:

gnaw "ERROR" test.log
```bash Terminal gnaw "ERROR" test.log ``` 
4: 2023-03-15 12:34:58,789 ERROR django.request: Internal Server Error: /api/v1/data/

Recursive Search

Search through directories:

gnaw -r "pattern" ./logs/

Count Matches

Get just the count of matching lines:

gnaw -c "ERROR" test.log

Chat Mode - Natural Language Search

Use natural language to describe your search:

gnaw --chat "Find all lines containing the word ERROR in any .log file in the logs directory"
```bash Terminal gnaw --chat "Find all error messages in log files" ``` 
Searching for error messages in log files...
Found 3 matches in 2 files:
- logs/app.log:2 matches
- logs/error.log:1 match

Dry Run

See what command would be generated without executing:

gnaw --chat "Show me lines with WARNING in server.log" --dry-run

Agent Mode - Semantic Code Search

The most powerful feature of gnaw is its AI-powered semantic search.

Build Code Index

First, build an index of your codebase:

gnaw agent index build

Semantic Search

Search for code by meaning, not just text:

# Find functions that handle authentication
gnaw agent ask "authentication functions"

# Find error handling patterns
gnaw agent ask "error handling" --type rs

# Search in specific directory
gnaw agent ask "database queries" --dir src/db
```bash Terminal gnaw agent ask "authentication functions" ``` 
Query: authentication functions

→ src/auth.rs (score: 0.95)
  Lines 15-25
  • Function definition matches query
  • Contains authentication keywords
  • High semantic similarity
  pub fn authenticate_user(token: &str) -> Result<User, AuthError> {
      // Authentication logic here
  }

JSON Output

Get structured output for programmatic consumption:

gnaw --json "ERROR" test.log
```bash Terminal gnaw --json "ERROR" test.log ``` 
{
  "search_term": "ERROR",
  "time_taken": "0.123s",
  "results": [
    {
      "file_name": "logs/app.log",
      "line_number": 42,
      "line": "2023-03-15 12:34:58,789 ERROR django.request: Internal Server Error: /api/v1/data/"
    }
  ]
}

Common Options

```bash # Show 2 lines before and after each match gnaw -C 2 "ERROR" test.log 
# Show 3 lines after each match
gnaw -A 3 "ERROR" test.log

# Show 1 line before each match
gnaw -B 1 "ERROR" test.log
```
```bash # Show only filenames with matches gnaw -l "pattern" ./logs/ 
# Show only filenames without matches
gnaw -L "pattern" ./logs/

# Show line numbers
gnaw -n "pattern" file.txt
```
```bash # Case insensitive search gnaw -i "error" test.log 
# Invert match (show non-matching lines)
gnaw -v "pattern" file.txt

# Count only
gnaw -c "pattern" file.txt
```

Next Steps

gnaw is designed to be a drop-in replacement for `grep` in most workflows. Try replacing `grep` with `gnaw` in your existing scripts!