ymr

README

ymr (pronounced ya·mr) is a lightweight, spec-driven command-line tool to generate YAML files from templates. It’s ideal for managing configuration across multiple environments or targets by replacing placeholders in your YAML templates with values defined in a central spec file.

Report Bug · Request Feature

---

TOC

• Why?
• How it Works
• Spec-less Mode
• Installation
• Usage
• Template Syntax
• Examples
• Contributing
• License

---

Why?

Existing YAML templating tools — such as jtt, Helm, Kustomize, or Kluctl — are powerful and versatile, but they often come with a steep learning curve and impose specific formatting or structural requirements on your YAML files.

ymr takes a simpler, more flexible approach. You simply add comments to your existing YAML configuration, and if they match your defined specifications, ymr performs the substitutions keeping the integrity of the YAML file. This means you can use ymr with any YAML file, including those already managed by other tools, without modifying your current workflow or file structure, and use any YAML linter you want.

(back to top)

How it Works

ymr processes YAML templates by substituting placeholders with values from your spec.yaml. It supports two main types of placeholders:

• from-param: {{ .var }} — replaces the entire value with the parameter {{ .var }}.
• from-param-merge: {{ .var }} — merges the parameter {{ .var }} into the existing YAML structure.

This allows for dynamic, reusable configuration generation — letting you define shared values once and selectively override them for specific environments or targets.

In addition, you can pipe the variables to the following functions:

• lower: to set all characters to lower case. Example: from-param: {{ .var | lower }}
• upper: to set all characters to upper case. Example: from-param: {{ .var | upper }}
• replace: to do string substitution. Example: from-param: {{ .var | replace "." "-" }}

Validations are also available if there is a need to enforce requirements. The policy engine uses the Common Expression Language (CEL) and it validates every parameter passed.

(back to top)

Spec-less Mode

ymr can be run without a spec.yaml file, which is useful for simple, one-off template rendering. In this mode, you must provide:

• A template file/URL via the --template (-T) flag.
• At least one parameter via the --param (-p) flag.

This mode is ideal for CI/CD pipelines or simple scripts where a full spec.yaml is unnecessary.

(back to top)

Installation

You can install ymr using go install:

go install github.com/lnrdll/ymr@latest

Alternatively, you can download the binary from the releases page.

(back to top)

Usage

ymr provides two main commands: init and run.

ymr init

Generates a boilerplate spec.yaml file in your current directory. This is a great starting point for new projects.

ymr init

Example `spec.yaml` generated by `init`:

# A list of templates to process.
# Paths are relative to the location of this spec.yaml.
templates:
  - base/service.yaml
  - base/configmap.yaml

# A simple list of target environments.
targetIds:
  - dev
  - prd

# A list of parameter sets.
parameters:
  # --- Shared values ---
  - targetId: ["dev", "prd"] # Which targets this value set applies to
    values:
      name: "myapp-name"

  # --- Dev-specific values ---
  - targetId: ["dev"]
    values:
      minScale: 1

  # --- Prod-specific values ---
  - targetId: ["prd"]
    values:
      minScale: 3
      maxScale: 10

In addition to the default boilerplate, the init command also accepts parameters so the boilerplate can be customized.

ymr init --templates service.yaml --target dev --target stg -p 'maxScale: 10' -p 'minScale: 1'

Custom `spec.yaml` example:

# A list of templates to process.
# Paths are relative to the location of this spec.yaml.
templates:
  - service.yaml

# A simple list of target environments.
targetIds:
  - dev
  - stg

# A list of parameter sets.
parameters:
  # --- Shared values for all provided targets ---
  - targetId:
      - dev
      - stg
    values:
      maxScale: 10
      minScale: 1
  # --- Specific values for target 'dev' ---
  - targetId: ["dev"]
    values:
      foo: bar
  # --- Specific values for target 'stg' ---
  - targetId: ["stg"]
    values:
      foo: bar

ymr run

Processes templates based on a spec.yaml file and generates output files.

ymr run [flags]

Flags:

• -s, --spec <path>: Source path for the spec.yaml (local, dir, file, http url, or github). Defaults to ./spec.yaml.
• -T, --template <path>: A single template file/URL to override the templates list in the spec.
• -o, --output <directory>: Output directory for rendered files. Use - for stdout.
• -p, --param <key=value>: Override a parameter (e.g., key=value). Can be used multiple times.
• -t, --target <id>: Override which targets to render. Can be used multiple times.
• --token <token>: GitHub token for accessing private repositories (or use GITHUB_TOKEN environment variable).
• --validation <path>: Path to a policy file. If provided, this will override any validations in the spec file.
• --debug: Enable debug logging.

Example ymr run usage:

# Specless mode
ymr run --template ./example/gcp-cloud-run/service.yaml -p version=111 -o -

# Process spec.yaml and output to the 'rendered' directory
ymr run -s spec.yaml -o rendered

# Override a parameter for a specific run
ymr run -s example/gcp-cloud-run -p minScale=5 -o -

# Render only the 'prd' target
ymr run -s example/gcp-cloud-run -t prd -o -

# Use a GitHub repo directly (requires --token or GITHUB_TOEKN env for private repos)
ymr run -s https://github.com/lnrdll/ymr/example/k8s@main -o -

# Run in spec-less mode
ymr run -T https://github.com/lnrdll/ymr/blob/main/example/k8s/deployment.yaml -t dev -p name=example -o -

(back to top)

Template Syntax

ymr uses special comments within your YAML templates to identify where parameters should be injected.

• # from-param: {{ .var }}: Replaces the entire value with the value of the parameter {{ .var }}.

  Template:

  replicas: 1 # from-param: {{ .replicas }}
  

  spec.yaml parameter:

  replicas: 3
  

  Output:

  replicas: 3
  

• # from-param-merge: {{ .var }}: Merges the YAML structure defined by the parameter {{ .var }} into the current location. This is useful for injecting complex objects or lists.

  Template:

  metadata:
    labels: # from-param-merge: {{ .commonLabels }}
      app: my-app
  

  spec.yaml parameter:

  commonLabels:
    environment: production
    version: v1.0.0
  

  Output:

  metadata:
    labels:
      app: my-app
      environment: production
      version: v1.0.0
  

Examples

The example directory contains a few examples of how to use ymr.

• simple: A simple example of how to use ymr with a single template and a single target.
• k8s: A more complex example of how to use ymr to generate Kubernetes manifests for multiple targets.
• gcp-cloud-run: An example of how to use ymr to generate a GCP Cloud Run service definition for multiple targets.
• docker-composer: An example of how to use ymr to generate a Docker Compose file for multiple targets.

To run the examples, cd into the example directory and run ymr run -o -:

cd example/simple
ymr run -s . -o -

(back to top)

Contributing

You're welcome to open issues or submit pull requests, though responses may take some time.

(back to top)

License

This project is licensed under the MIT License. See the LICENSE file for details.

(back to top)

Disclaimer

I originally started this project to address a specific challenge with service deployments and YAML. Over time, I decided to also use it as a testbed for experimenting with various LLMs. As a result, this repository will serve as a playground for trying out different LLMs and related tools.

I will ensure that no changes introduced through LLM experimentation are merged if they could potentially break existing functionality.

At the time of writing, only the logo and some test cases have been created using LLMs.