cli-ninja

What this skill does

# 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