cli-ninja

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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# Pipe any list to fzf for selection
command | fzf

# Multi-select mode
command | fzf -m

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

Preview configurations:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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:

   # 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

# 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