yaml-rt-cli 0.3.4

Presentation-preserving command-line YAML query and editor
Documentation

yaml-rt-cli

Crates.io docs.rs CI Playground

The yaml-rt command-line query and editor for YAML 1.2.2. Query with RFC 9535 JSONPath and edit with RFC 6901 JSON Pointers while preserving unrelated comments, whitespace, scalar spelling, and collection styles.

Installation

Requires Rust 1.96 or newer to build.

cargo install yaml-rt-cli --locked

The package name is yaml-rt-cli; the installed binary is yaml-rt. Try commands in the browser playground.

Query and edit

For a first edit, save this as config.yaml:

# local development
server:
  port: 8080 # user choice
yaml-rt replace /server/port --value 9090 config.yaml

The command prints the following YAML, leaving the file unchanged:

# local development
server:
  port: 9090 # user choice

Use --in-place to save the change. The additional commands below illustrate other operations; adjust paths and input files to match your configuration.

# Validate YAML, optionally against a JSON or YAML schema.
yaml-rt validate config.yaml
yaml-rt validate --schema config.schema.json config.yaml

# Infer a permissive JSON Schema from one document.
yaml-rt schema config.yaml --output config.schema.json

# Print JSON Pointer/value pairs for matching nodes.
yaml-rt query '$.services[*].port' config.yaml

# Read a value, or emit each query match as a YAML document.
yaml-rt get /server/port config.yaml
yaml-rt get --query '$.services[*].port' config.yaml

# Print edited YAML or replace the file atomically.
yaml-rt replace /server/port --value 9090 config.yaml
yaml-rt replace --query '$.services[*].port' --value 9090 --in-place config.yaml

# Rename a key while preserving its entry position and comments.
yaml-rt rename-key /server/old-name --to new-name config.yaml

# Insert a complete YAML node from another file.
yaml-rt add /server/tls --value-file tls.yaml config.yaml

# Select the second document in a stream (zero-based).
yaml-rt get /name --doc 1 stream.yaml

Operations are validate, schema, query, get, add, remove, replace, rename-key, move, copy, test, and patch. Use yaml-rt help <operation> for arguments. get, add, remove, replace, rename-key, and test accept --query instead of a positional pointer. Query mutations apply transactionally to all selected targets; mutations and test fail if nothing matches.

Transactional patches

Save this YAML as changes.yaml:

- op: test
  path: /server/port
  value: 8080
- op: replace
  path: /server/port
  value: 9090
yaml-rt patch --patch-file changes.yaml --in-place config.yaml

Patch input can be YAML or JSON and follows RFC 6902-style operations with full YAML node values. Operations run in order; any failure rolls back the entire patch for that document. --patch accepts inline input. --patch-file - reads stdin when the target document does not also read stdin.

Files, batches, and output

Input can be a file, a directory, or - for stdin. Omitted input scans the current directory. Directories recursively include .yaml and .yml files (case-insensitive), including hidden paths, in sorted relative-path order; symlinks are skipped.

Single-file edits print YAML unless --output FILE or --in-place is supplied. Batch edits require --in-place and replace each successful file atomically. Failures do not stop remaining files; any failure produces an unsuccessful exit. Batch read output identifies files with headers, and --output collects that output into one file. Successful validate produces no output.

Parse errors include source excerpts, file names, lines, and columns. Terminal colors follow stderr interactivity and NO_COLOR.

Limits

JSONPath validates the entire selected document for JSON compatibility before selecting nodes. For example, get --query '$.server.port' fails if any unrelated field contains .inf; get /server/port config.yaml can still read that known path. Schema validation also requires JSON-compatible YAML. Schema references may use local files; network fetches are unavailable. Key rename supports plain and quoted string keys, but not complex, alias, or block-scalar keys. Copy and move reject ambiguous or invalid anchor ownership. Parser resource limits are enabled by default. Untouched documents remain byte-identical; this tool does not canonicalize formatting.

Links and license

API documentation · Repository

Licensed under either Apache-2.0 or MIT, at your option.