yq: YAML/JSON Query Tool

Extract specific fields from YAML and JSON files without reading entire contents into context.

When to Use

Use yq when:

• Need specific field(s) from YAML/JSON config
• File is large (>50 lines) and only need subset
• Querying nested structures
• Working with docker-compose, GitHub Actions, K8s, Helm charts

Just use Read when:

• File is small (<50 lines)
• Need to understand overall structure
• Making edits (need full context anyway)

Common Files

• docker-compose.yml - services, ports, volumes, networks
• .github/workflows/*.yml - triggers, jobs, steps
• kubernetes/*.yaml - deployments, services, configmaps
• pubspec.yaml - Flutter/Dart dependencies
• package.json - npm dependencies (use jq)
• tsconfig.json - TypeScript config (use jq)

Quick Reference

# Get specific field
yq '.version' pubspec.yaml
yq '.services.web.image' docker-compose.yml

# Get all keys at level
yq '.services | keys' docker-compose.yml

# Get nested array element
yq '.jobs.build.steps[0].name' .github/workflows/ci.yml

# Filter by condition
yq '.services.[] | select(.ports)' docker-compose.yml

# Multiple fields
yq '.name, .version' pubspec.yaml

# Output as JSON
yq -o=json '.' config.yaml

jq for JSON

Same patterns, different tool:

# Get dependency version
jq '.dependencies["react"]' package.json

# Get all script names
jq '.scripts | keys' package.json

# Get compiler options
jq '.compilerOptions.target' tsconfig.json

Docker Compose Patterns

# List all services
yq '.services | keys' docker-compose.yml

# Get ports for a service
yq '.services.web.ports' docker-compose.yml

# Get all images
yq '.services.*.image' docker-compose.yml

# Get environment variables
yq '.services.api.environment' docker-compose.yml

GitHub Actions Patterns

# Get workflow triggers
yq '.on' .github/workflows/ci.yml

# List all jobs
yq '.jobs | keys' .github/workflows/ci.yml

# Get steps for a job
yq '.jobs.build.steps[].name' .github/workflows/ci.yml

# Get runs-on value
yq '.jobs.build.runs-on' .github/workflows/ci.yml

Kubernetes Patterns

# Get container image
yq '.spec.template.spec.containers[0].image' deployment.yaml

# Get replicas
yq '.spec.replicas' deployment.yaml

# Get all labels
yq '.metadata.labels' service.yaml

# Get ports
yq '.spec.ports' service.yaml

Core Principle

Extract exactly what's needed in one command. Saves 80-95% context vs reading entire config files.