gy

README

gy - grep for YAML

A fast, lightweight command-line tool for extracting, exploring, and navigating YAML documents.

Features

• 🎯 Path-based extraction - Navigate YAML with simple dot notation
• 📋 List mode - Explore document structure interactively
• 🔍 Trim mode - Extract just the data you need
• 📥 Pipe-friendly - Works with files or stdin
• ⚡ Fast - Single binary, minimal overhead

Installation

Download a prebuilt binary from the releases page (Linux, macOS, and Windows; amd64 and arm64), or build it yourself:

git clone https://github.com/tsettle/gy
cd gy
go build gy.go
sudo cp gy /usr/local/bin/

Or install directly:

go install github.com/tsettle/gy@latest

Quick Start

Given this config.yml:

database:
  host: localhost
  port: 5432
  credentials:
    user: admin
    password: secret
services:
  - name: web
    port: 8080
  - name: api
    port: 3000

Basic Extraction

# Extract with full path preserved
$ gy 'database.host' config.yml
database:
  host: localhost

# Extract just the value
$ gy -t 'database.host' config.yml
localhost

# Navigate into nested structures
$ gy 'database.credentials' config.yml
database:
  credentials:
    user: admin
    password: secret

Array Access

# Access array elements by index
$ gy 'services[0]' config.yml
services:
  - name: web
    port: 8080

# Navigate into array elements
$ gy -t 'services[1].name' config.yml
api

# Trim mode works great with arrays
$ gy -t 'services[0].port' config.yml
8080

Discovery Mode

# List top-level keys
$ gy -l '.' config.yml
database
services

# List with depth
$ gy -l --depth 2 'database' config.yml
database
  host
  port
  credentials
    user
    password

# Explore array contents
$ gy -l 'services[0]' config.yml
name
port

Piping and Composition

# Read from stdin
$ cat config.yml | gy 'database.credentials'

# Chain with other tools
$ gy -t 'services[0].name' config.yml | tr '[:lower:]' '[:upper:]'
WEB

# Use in scripts
$ DB_HOST=$(gy -t 'database.host' config.yml)
$ echo "Connecting to $DB_HOST"

Usage

gy [OPTIONS] <path> [filename]

Options

Flag	Description
-t, --trim	Return only the matched node (no path wrapping)
-l, --list	List all keys/indices under the path
--depth N	Control listing depth (default: 1, use 0 for unlimited)
-j, --flow	Force flow-style ({}/[]) output (mnemonic: json)
-y, --block	Force block-style (indented) output (mnemonic: yaml)

Path Syntax

• Dot notation: path.to.key
• Array indexing: path.to.array[0]
• Combined: users[0].profile.email
• Root: . or leave empty to reference the entire document

JSON

JSON is valid YAML flow syntax, so gy reads .json files natively - no flag needed:

$ gy 'database.host' config.json
{"database": {"host": "localhost"}}

Output matches the input's style by default: extracting from JSON stays flow-style/JSON-shaped, extracting from block YAML stays block YAML. Override either way with -j/--flow or -y/--block:

# Turn a block YAML doc into flow-style/JSON-like output
$ gy -j 'database' config.yml
{database: {host: localhost, port: 5432}}

# Turn a JSON doc into indented block YAML
$ gy --block 'database' config.json
"database":
    "host": "localhost"
    "port": 5432

Common Patterns

Configuration Management

# Extract database config for deployment
gy 'database' prod.yml > db-config.yml

# Get specific credentials
export DB_PASS=$(gy -t 'database.credentials.password' config.yml)

Exploration

# Quick overview of document structure
gy -l --depth 3 '.' large-config.yml

# Find all available modules
gy -l 'modules' snmp.yml

Validation

# Check if a path exists
if gy 'database.host' config.yml > /dev/null 2>&1; then
    echo "Database configured"
fi

Data Extraction

# Extract multiple configs in a script
for service in web api worker; do
    gy "services.$service" config.yml > "$service-config.yml"
done

Real-World Examples

SNMP Configuration

# List all monitoring modules
gy -l 'modules' snmp.yml

# Extract specific MIB walks
gy --trim 'modules.if_mib.walk' snmp.yml > if_mib_walk.yml

# Get first OID from a walk
gy -t 'modules.if_mib.walk[0]' snmp.yml

Kubernetes Manifests

# Extract container specs
gy 'spec.template.spec.containers[0]' deployment.yml

# List all environment variables
gy -l 'spec.template.spec.containers[0].env' deployment.yml

CI/CD Pipelines

# Extract job definitions
gy '.github.workflows.build.jobs' .github/workflows/ci.yml

# Get specific job steps
gy -t '.github.workflows.build.jobs.test.steps[0]' ci.yml

Roadmap

• Wildcard support - gy 'users[*].name' to extract from all array items
• Glob patterns - gy 'services.*.port' for flexible matching
• Merge functionality - gy --merge target.yml 'path.to.data' source.yml
• Flat list mode - Output full paths on single lines for grep compatibility
• Multiple patterns - gy 'path1,path2,path3'
• JSON support - JSON input works natively; --flow/--block convert between JSON-like and indented YAML output
• Named lists - gy '@name:Deploy web application stack' ansible.yml
• Key/Value - Return any paths matching a key and/or value.
• Broken tests - Fix broken tests then create more broken tests to fix.

Testing

go test ./...

Unit tests (gy_internal_test.go) exercise path parsing and node extraction directly. End-to-end tests (cli_test.go) build the binary and run it as a subprocess against the fixtures in test/, asserting exact stdout/stderr/exit codes. test_examples.sh is a separate showcase script for manually eyeballing output - it isn't part of the assertion-backed suite.

Contributing

Contributions welcome! Please feel free to submit issues or pull requests.

License

MIT License - see LICENSE file for details

Similar Tools

• yq - Feature-rich YAML processor (uses YAML→JSON→YAML conversion)
• jq - JSON processor that inspired this tool
• dasel - Unified selector for JSON/YAML/TOML/XML

Why gy? Because yq doesn't preserve paths in output without bracket gymnastics, converts YAML→JSON→YAML (destroying types, comments, and anchors), and sometimes you just need to extract a chunk from a 1.5MB YAML file and merge it into another without your 1: keys becoming "1": strings. Built for the 90% use case: extract, preserve structure, preserve types, move on with your life.