YAML Command Line Interface (CLI)

1.1.8 verified Thu Apr 23 auth: no javascript deprecated

yaml-cli is a command-line interface tool designed for directly interacting with YAML files, providing functionalities such as querying values, setting properties, instantiating templates, and converting between YAML and JSON formats. Currently at version 1.1.8, this project has been officially deprecated. While it offers a simple and direct approach to YAML manipulation via shell commands, its developers now recommend using `yq` as a more actively maintained and feature-rich alternative. Key differentiators of yaml-cli include its intuitive dot-notation for nested property access and array indexing, and its built-in templating engine. Users should be aware of its deprecated status and consider migrating to `yq` for new projects or ongoing maintenance to ensure continued support and access to new features.

Common errors

error yaml: command not found ↓

cause The `yaml-cli` package was not installed globally or its executable is not in the system's PATH.

fix

Install the package globally using npm install -g yaml-cli or ensure that the npm global bin directory is included in your system's PATH environment variable.

error (<unknown>): mapping values are not allowed in this context at line X column Y ↓

cause This error typically indicates an indentation problem or a missing quote around a string value that contains special characters or is being misinterpreted by the YAML parser.

fix

Review the YAML file at the specified line and column. Correct any inconsistent indentation (use spaces, not tabs). If a string contains special characters (like : or spaces in a key, or yes/no/true/false values that should be strings), enclose it in single or double quotes.

Warnings

breaking This `yaml-cli` project (pandastrike/yaml-cli) has been officially deprecated by its maintainers. It is no longer under active development and new features or bug fixes should not be expected. Users are strongly encouraged to migrate to `yq` (https://github.com/mikefarah/yq) for robust and actively maintained YAML processing functionality. ↓

fix Migrate to `yq` which provides similar and enhanced capabilities. Update scripts and workflows to use `yq` commands instead of `yaml-cli`.

gotcha YAML files are highly sensitive to indentation. Using tabs instead of spaces, or inconsistent spacing, will lead to parsing errors and unexpected behavior, often resulting in obscure error messages or malformed output. ↓

fix Always use spaces for indentation, maintaining a consistent number of spaces (e.g., 2 or 4) throughout the file. Utilize a YAML-aware text editor or linter to catch indentation issues early. The `yamllint` tool (available via `npm install -g yamllint`) can help validate syntax.

gotcha Values in YAML files can be interpreted differently based on their content (e.g., 'true' might be a boolean, '7' an integer). Strings containing special characters or what might look like boolean/numeric values (e.g., 'no', 'on', '0.1') should be explicitly quoted to ensure they are parsed as strings. ↓

fix Enclose any ambiguous values in single or double quotes (e.g., `value: '7'`, `status: 'no'`, `country: 'NO'`) to force string interpretation.

Install

npm install yaml-cli

yarn add yaml-cli

pnpm add yaml-cli

Quickstart

This quickstart demonstrates how to globally install `yaml-cli`, create a sample YAML file, then use `yaml-cli` to `get` a specific value, `set` a new value, and finally `json write` the updated YAML content to standard output in JSON format.

# Install the CLI globally
npm install -g yaml-cli

# Create a sample YAML file
cat << EOF > mydata.yaml
user:
  name: Alice
  settings:
    theme: dark
    notifications: true
items:
  - id: 1
    name: Item A
  - id: 2
    name: Item B
EOF

echo "Original YAML:"
cat mydata.yaml
echo "\n"

# Get a value
echo "Getting user name:"
yaml get mydata.yaml user.name
echo "\n"

# Set a value
echo "Setting user theme to light:"
yaml set mydata.yaml user.settings.theme light
echo "\n"

echo "Updated YAML:"
cat mydata.yaml
echo "\n"

# Convert to JSON
echo "Converting to JSON:"
yaml json write mydata.yaml