claude-mods/rules/cli-tools.md

CLI Tool Preferences (dev-shell-tools)

ALWAYS prefer modern CLI tools over traditional alternatives. These are pre-approved in permissions.

File Search & Navigation

Instead of	Use	Why
find	fd	5x faster, simpler syntax, respects .gitignore
grep	rg (ripgrep)	10x faster, respects .gitignore, better defaults
ls	eza	Git status, icons, tree view built-in
cat	bat	Syntax highlighting, line numbers, git integration
cd + manual	z/zoxide	Jump to frecent directories
tree	broot or eza --tree	Interactive, filterable

Examples

# Find files (use fd, not find)
fd "\.ts$"                    # Find TypeScript files
fd -e py                      # Find by extension

# Search content (use rg, not grep)
rg "TODO"                     # Search for TODO
rg -t ts "function"           # Search in TypeScript files

# List files (use eza, not ls)
eza -la --git                 # List with git status
eza --tree --level=2          # Tree view

# View files (use bat, not cat)
bat src/index.ts              # Syntax highlighted

Data Processing

Instead of	Use	Why
sed	sd	Simpler syntax, no escaping headaches
Manual JSON	jq	Structured queries, transformations
Manual YAML	yq	Same as jq but for YAML/TOML

# Find and replace (use sd, not sed)
sd 'oldText' 'newText' file.txt

# JSON processing
jq '.dependencies | keys' package.json

# YAML processing
yq '.services | keys' docker-compose.yml

Document Conversion

Instead of	Use	Why
PyMuPDF/pdfplumber	markitdown	One tool for PDF, Word, Excel, PowerPoint
python-docx	markitdown	Consistent markdown output
Manual OCR	markitdown	Built-in image text extraction

# Convert documents to markdown (use markitdown)
markitdown document.pdf           # PDF to markdown
markitdown report.docx            # Word to markdown
markitdown data.xlsx              # Excel to markdown tables
markitdown slides.pptx            # PowerPoint to markdown
markitdown screenshot.png         # OCR image text

Git Operations

Instead of	Use	Why
git diff	delta or difft	Syntax highlighting, side-by-side
git log/status/add	lazygit	Full TUI, faster workflow
GitHub web	gh	CLI for PRs, issues, actions

# Better diffs
git diff | delta              # Syntax highlighted diff
difft file1.ts file2.ts       # Semantic AST diff

# GitHub operations
gh pr create                  # Create PR from CLI
gh pr list                    # List PRs

Code Analysis

Task	Tool
Line counts	tokei
AST search	ast-grep / sg
Benchmarks	hyperfine

# Count lines by language
tokei --compact

# Search by AST pattern (find all console.log calls)
sg -p 'console.log($$$)' -l js

# Benchmark commands
hyperfine 'fd . -e ts' 'find . -name "*.ts"'

System Monitoring

Instead of	Use	Why
du -h	dust	Visual tree sorted by size
top/htop	btm (bottom)	Graphs, cleaner UI (optional)

# Disk usage (use dust, not du)
dust                          # Visual tree sorted by size
dust -d 2                     # Limit depth

Note: ps is fine for shell process checks. Use procs only when you need full system process monitoring with CPU/memory stats.

Interactive Selection

Task	Tool
Fuzzy file find	fzf + fd
Interactive grep	fzf + rg
History search	Ctrl+R (fzf)
Git branch select	git branch \| fzf

# Fuzzy find and open file
fd --type f | fzf | xargs bat

# Interactive grep results
rg --line-number . | fzf --preview 'bat --color=always {1} --highlight-line {2}'

# Select git branch
git checkout $(git branch | fzf)

# Kill process interactively
procs | fzf | awk '{print $1}' | xargs kill

Documentation

Instead of	Use	Why
man <cmd>	tldr <cmd>	98% smaller, practical examples only

# Quick command reference (use tldr, not man)
tldr git-rebase               # Concise examples
tldr tar                      # No more forgetting tar flags

Python

Instead of	Use	Why
pip	uv	10-100x faster installs
python -m venv	uv venv	Faster venv creation

uv venv .venv
uv pip install -r requirements.txt

Task Running

Prefer just over Makefiles:

just                          # List available tasks
just test                     # Run test task

Web Fetching (URL Retrieval)

When fetching web content, use this hierarchy based on benchmarked performance:

Priority	Tool	Speed	Use Case
1	WebFetch	Instant	First attempt - built-in
2	r.jina.ai/URL	0.5s avg	Default fallback - 5-10x faster than alternatives
3	firecrawl <url>	4-5s avg	Anti-bot bypass, Cloudflare, heavy JS
4	markitdown <url>	2-3s avg	Simple static pages (or local files)

# Jina Reader - fastest option (free, 10M tokens)
curl https://r.jina.ai/https://example.com

# Jina Search - search + fetch in one call
curl https://s.jina.ai/your%20search%20query

# Firecrawl CLI - anti-bot bypass
firecrawl https://blocked-site.com
firecrawl https://example.com --json

# markitdown - simple pages or local files
markitdown https://example.com
markitdown document.pdf

Decision Tree:

1. Try WebFetch first (instant, free)
2. If blocked → Try Jina: r.jina.ai/URL (fastest, 10/10 success rate)
3. If anti-bot/Cloudflare → Try firecrawl <url> (designed for bypass)
4. For local files (PDF, Word, Excel) → Use markitdown

Reference

Tools from: https://github.com/0xDarkMatter/claude-mods/tree/main/tools

Install all tools:

# Windows (as Admin)
.\tools\install-windows.ps1

# Linux/macOS
./tools/install-unix.sh