---
name: cli-ninja
description: Master CLI navigation and code exploration using modern command-line tools. Use this skill when navigating repositories, searching for files/text/code patterns, or working with structured data (JSON/YAML/XML). Provides guidance on fd (file finding), rg (text search), ast-grep (code structure), fzf (interactive selection), jq (JSON), and yq (YAML/XML).
---

# CLI Ninja

## Overview

This skill provides guidance for efficient repository navigation and code exploration using modern CLI tools. Each tool serves a specific purpose: `fd` for finding files, `rg` for searching text, `ast-grep` for understanding code structure, `fzf` for interactive selection, `jq` for JSON manipulation, and `yq` for YAML/XML processing.

## Tool Selection Decision Tree

When navigating or exploring a repository, choose the appropriate tool based on the task:

```
What are you looking for?

├─ FILES by name/path/extension?
│  └─ Use: fd
│     └─ Need to select from results? → Pipe to fzf
│
├─ TEXT/STRINGS in file contents?
│  └─ Use: rg (ripgrep)
│     └─ Need to select from results? → Pipe to fzf
│
├─ CODE STRUCTURE (functions, classes, imports)?
│  └─ Use: ast-grep
│     └─ Need to select from results? → Pipe to fzf
│     └─ Need to refactor/replace? → Use ast-grep --rewrite
│
├─ Working with JSON data?
│  └─ Use: jq
│
└─ Working with YAML or XML data?
   └─ Use: yq
```

## Quick Reference Guide

### fd - Find Files

**Basic patterns:**
```bash
# Find by name
fd 'pattern'

# Find by extension
fd -e py          # All Python files
fd -e 'test.py$'  # Files ending in test.py

# Find in specific directory
fd 'pattern' src/

# Case-insensitive
fd -i readme

# Hidden files
fd -H '.env'

# Exclude patterns
fd -e py -E '*test*'
```

**Common workflows:**
```bash
# Find and edit a config file interactively
fd config | fzf | xargs $EDITOR

# Find all Python files modified in last 7 days
fd -e py -td --changed-within 7d

# Find files by size
fd -e db --size +100m
```

See `references/fd-patterns.md` for comprehensive patterns and flags.

### rg - Search Text/Strings

**Basic patterns:**
```bash
# Basic search
rg 'search_term'

# Case-insensitive
rg -i 'search_term'

# Whole word only
rg -w 'word'

# With context lines
rg -C 3 'pattern'        # 3 lines before/after
rg -B 2 -A 5 'pattern'   # 2 before, 5 after

# Specific file types
rg -t py 'import'        # Python files
rg -t rust 'fn main'     # Rust files
```

**Advanced usage:**
```bash
# Search with line numbers and file names
rg -n 'pattern'

# Multiline search
rg -U 'pattern.*spanning.*lines'

# Exclude patterns
rg 'TODO' -g '!*test*'

# Search in specific directories
rg 'pattern' src/ core/

# JSON output for scripting
rg --json 'pattern'
```

**Interactive workflows:**
```bash
# Search and open in editor
rg -l 'TODO' | fzf | xargs $EDITOR

# Search with preview
rg --line-number 'pattern' | fzf --preview 'bat --color=always {1} --highlight-line {2}'
```

See `references/rg-patterns.md` for regex tips and advanced patterns.

### ast-grep - Find Code Structure

**Philosophy:** ast-grep searches code by structure, not strings. It understands programming language syntax and semantics.

**Basic patterns:**

**Python:**
```bash
# Find all function definitions
ast-grep --pattern 'def $FUNC($$$)' -l py

# Find specific function calls
ast-grep --pattern 'player.play($$$)' -l py

# Find class definitions
ast-grep --pattern 'class $CLASS:' -l py

# Find all imports of a module
ast-grep --pattern 'from $MOD import $$$' -l py
ast-grep --pattern 'import $MOD' -l py

# Find type annotations
ast-grep --pattern 'def $FUNC($$$) -> $TYPE:' -l py
```

**JavaScript/TypeScript:**
```bash
# Find React components
ast-grep --pattern 'function $COMP() { $$$ }' -l tsx

# Find useState hooks
ast-grep --pattern 'const [$STATE, $SETTER] = useState($$$)' -l tsx

# Find async functions
ast-grep --pattern 'async function $FUNC($$$) { $$$ }' -l js

# Find imports
ast-grep --pattern 'import $$ from "$MODULE"' -l ts
```

**Rust:**
```bash
# Find function definitions
ast-grep --pattern 'fn $FUNC($$$) { $$$ }' -l rs

# Find struct definitions
ast-grep --pattern 'struct $NAME { $$$ }' -l rs

# Find impl blocks
ast-grep --pattern 'impl $TRAIT for $TYPE { $$$ }' -l rs

# Find macro usage
ast-grep --pattern 'println!($$$)' -l rs
```

**Go:**
```bash
# Find function definitions
ast-grep --pattern 'func $FUNC($$$) $$$ { $$$ }' -l go

# Find struct definitions
ast-grep --pattern 'type $NAME struct { $$$ }' -l go

# Find interface implementations
ast-grep --pattern 'func ($RECV $TYPE) $METHOD($$$) $$$ { $$$ }' -l go

# Find goroutines
ast-grep --pattern 'go $FUNC($$$)' -l go
```

**Zig:**
```bash
# Find function definitions
ast-grep --pattern 'pub fn $FUNC($$$) $$$ { $$$ }' -l zig

# Find struct definitions
ast-grep --pattern 'const $NAME = struct { $$$ };' -l zig

# Find test functions
ast-grep --pattern 'test "$NAME" { $$$ }' -l zig

# Find error handling
ast-grep --pattern 'try $EXPR' -l zig
```

**Ruby:**
```bash
# Find method definitions
ast-grep --pattern 'def $METHOD($$$); $$$; end' -l rb

# Find class definitions
ast-grep --pattern 'class $CLASS; $$$; end' -l rb

# Find blocks
ast-grep --pattern '$EXPR do |$PARAM|; $$$; end' -l rb

# Find Rails routes
ast-grep --pattern 'get "$PATH", to: "$HANDLER"' -l rb
```

**Refactoring with ast-grep:**
```bash
# Rename a function across the codebase
ast-grep --pattern 'old_function($$$)' --rewrite 'new_function($$$)' -l py --interactive

# Update API calls
ast-grep --pattern 'api.v1.$METHOD($$$)' --rewrite 'api.v2.$METHOD($$$)' -l py

# Modernize code patterns
ast-grep --pattern 'var $VAR = $EXPR' --rewrite 'const $VAR = $EXPR' -l js
```

**Interactive workflows:**
```bash
# Find and select a function to edit
ast-grep --pattern 'def $FUNC($$$)' -l py | fzf | cut -d: -f1 | xargs $EDITOR

# Find all TODOs in code comments (use rg instead)
rg 'TODO|FIXME' | fzf
```

See `references/ast-grep-guide.md` for comprehensive patterns across all languages.

### fzf - Interactive Selection

**Basic usage:**
```bash
# Pipe any list to fzf for selection
command | fzf

# Multi-select mode
command | fzf -m

# With preview window
command | fzf --preview 'bat {}'
```

**Preview configurations:**
```bash
# Preview files with syntax highlighting
fd -t f | fzf --preview 'bat --color=always {}'

# Preview with line numbers
rg --line-number 'pattern' | fzf --preview 'bat --color=always {1} --highlight-line {2}'

# Preview JSON files
fd -e json | fzf --preview 'jq . {}'

# Custom preview window size
fzf --preview 'cat {}' --preview-window=right:50%
```

**Keybindings:**
```bash
# ctrl-t: Paste selected files
# ctrl-r: Paste from history
# alt-c: cd into selected directory

# Custom keybindings
fzf --bind 'ctrl-y:execute-silent(echo {} | pbcopy)'
```

See `references/fzf-workflows.md` for advanced interactive workflows.

### jq - JSON Processing

**Basic queries:**
```bash
# Pretty print
jq . file.json

# Extract field
jq '.name' file.json

# Array indexing
jq '.[0]' file.json

# Nested access
jq '.user.name' file.json

# Array operations
jq '.[] | .name' file.json
```

**Common transformations:**
```bash
# Filter arrays
jq '.users[] | select(.active == true)' file.json

# Map over arrays
jq '.users | map(.name)' file.json

# Sorting
jq '.users | sort_by(.age)' file.json

# Group by
jq 'group_by(.category)' file.json

# Count items
jq '.items | length' file.json

# Keys extraction
jq 'keys' file.json
```

**Advanced usage:**
```bash
# Multiple filters
jq '.users[] | select(.age > 18) | .name' file.json

# Construct new objects
jq '{name: .firstName, email: .emailAddress}' file.json

# Combine multiple files
jq -s '.[0] + .[1]' file1.json file2.json

# Read from stdin
curl -s https://api.example.com/data | jq '.results[]'
```

See `references/jq-cookbook.md` for comprehensive transformations.

### yq - YAML/XML Processing

**YAML queries:**
```bash
# Pretty print
yq . file.yaml

# Extract field
yq '.name' file.yaml

# Nested access
yq '.services.web.image' docker-compose.yml

# Array operations
yq '.dependencies[]' file.yaml

# Convert to JSON
yq -o json . file.yaml
```

**XML queries:**
```bash
# Parse XML
yq -p xml . file.xml

# Extract elements
yq -p xml '.root.element' file.xml

# Convert XML to JSON
yq -p xml -o json . file.xml
```

**Common operations:**
```bash
# Update values
yq '.version = "2.0"' file.yaml

# Merge files
yq '. *= load("other.yaml")' file.yaml

# Filter arrays
yq '.items[] | select(.enabled == true)' file.yaml
```

See `references/yq-examples.md` for YAML/XML processing patterns.

## Combination Workflows

Real-world tasks often combine multiple tools:

### 1. Find and Edit Files with Context

```bash
# Find Python files containing a function, preview them, then edit
rg -l 'def process_data' -t py | fzf --preview 'rg -C 5 "def process_data" {}' | xargs $EDITOR
```

### 2. Code Refactoring Workflow

```bash
# Find all usages of a function across the codebase
ast-grep --pattern 'old_function($$$)' -l py | fzf -m

# Then refactor with interactive confirmation
ast-grep --pattern 'old_function($$$)' --rewrite 'new_function($$$)' -l py --interactive
```

### 3. Interactive Configuration Explorer

```bash
# Find config files and explore their structure
fd -e json -e yaml | fzf --preview 'bat --color=always {} --style=numbers'

# Or with jq/yq preview
fd -e json | fzf --preview 'jq . {}'
fd -e yaml | fzf --preview 'yq . {}'
```

### 4. Find Related Code

```bash
# Find a class definition, then find all its usages
CLASS=$(ast-grep --pattern 'class $NAME:' -l py | fzf | cut -d: -f2)
rg -w "$CLASS" --type py
```

### 5. Dependency Analysis

```bash
# Find all imports of a module
ast-grep --pattern 'from mymodule import $$$' -l py -t python

# Combine with text search for dynamic imports
rg 'importlib.*mymodule' -t py
```

### 6. Multi-File Search and Replace

```bash
# Find files with pattern, select multiple, and apply changes
rg -l 'TODO.*urgent' | fzf -m | xargs sed -i '' 's/TODO.*urgent/DONE/g'
```

### 7. Code Structure Analysis

```bash
# Find all functions in a module, count them
ast-grep --pattern 'def $FUNC($$$)' -l py src/module.py | wc -l

# Find function complexity (functions with many parameters)
ast-grep --pattern 'def $FUNC($A, $B, $C, $D, $E, $$$)' -l py
```

See `scripts/combo-search.sh` and `scripts/interactive-code-finder.sh` for reusable combination workflows.

## Best Practices

### Performance Tips

1. **Use the right tool for the job:**
   - File names → `fd`
   - Text content → `rg`
   - Code structure → `ast-grep`

2. **Narrow your search scope:**
   ```bash
   # Good: Search specific directory
   rg 'pattern' src/

   # Better: Search specific file types
   rg 'pattern' -t py src/
   ```

3. **Use `.gitignore` respect:**
   - Both `fd` and `rg` respect `.gitignore` by default
   - Use `-u` or `--no-ignore` to override when needed

### Pattern Matching Tips

1. **ast-grep patterns:**
   - Use `$VAR` for single identifiers
   - Use `$$$` for arbitrary code sequences
   - Use `$$` for statement lists

2. **ripgrep regex:**
   - Use `-F` for literal strings (faster)
   - Use `-w` for whole words
   - Use `\b` for word boundaries

3. **fzf fuzzy matching:**
   - Space for AND search: `foo bar` matches files with both
   - `|` for OR search: `foo|bar`
   - `^` for prefix match, `$` for suffix match

### Debugging Searches

```bash
# See what rg is searching
rg --debug 'pattern' 2>&1 | head -20

# Dry-run ast-grep refactoring
ast-grep --pattern 'old' --rewrite 'new' --interactive

# Test jq queries incrementally
echo '{"name":"test"}' | jq .
echo '{"name":"test"}' | jq '.name'
```

## Resources

This skill includes bundled resources to support CLI navigation:

### scripts/

Example scripts demonstrating tool combinations:

- `combo-search.sh` - Common combination workflows
- `interactive-code-finder.sh` - Interactive ast-grep + fzf workflow

### references/

Comprehensive guides for each tool:

- `fd-patterns.md` - File finding patterns and flags
- `rg-patterns.md` - Text search patterns and regex tips
- `ast-grep-guide.md` - Code structure patterns for Python, Zig, Go, Ruby, JS/TS, Rust
- `fzf-workflows.md` - Interactive selection and preview configurations
- `jq-cookbook.md` - JSON transformations and filters
- `yq-examples.md` - YAML/XML processing examples