Getting Started

This guide gets you from an empty GitOps source project to rendered Kubernetes manifests, then points you at the workflow that matches how you deploy.

Installation

With mise

Add Nyl to your mise.toml:

[tools."github:NiklasRosenstein/nyl"]
version = "0.4.1"
version_prefix = "v"

Then install it:

mise install

From Release

curl -LO https://github.com/NiklasRosenstein/nyl/releases/latest/download/nyl-x86_64-unknown-linux-gnu.tar.gz
tar xzf nyl-x86_64-unknown-linux-gnu.tar.gz
sudo mv nyl /usr/local/bin/

From Source

cd nyl
cargo build --release

The binary will be available at nyl/target/release/nyl when building from the repository root.

Install Locally

cd nyl
cargo install --path .

This installs nyl to ~/.cargo/bin/nyl.

Quick Start

1. Create a Project

   nyl init platform --minimal
   cd platform

   This creates:

   • nyl.toml - Project configuration
   • components/ - Directory for components
   • applications/ - Application sources
   • config/ - Cluster, target, repository, and Argo CD policy resources

2. Add a Component

   nyl create component v1.example.io MyApp

   This creates a new local component at components/v1.example.io/MyApp/ with:

   • Chart.yaml - Helm chart metadata
   • values.yaml - Default values
   • values.schema.json - JSON schema for validation
   • templates/deployment.yaml - Kubernetes deployment template

3. Validate

   $ nyl validate
   ✓ Found project config: nyl.toml
   ✓ Components search path exists: components
   ✓ Helm chart search path exists: .
   
   ✓ Validation passed

   For CI, use strict mode to treat warnings as errors:

   nyl validate --strict

4. Render

   Render a manifest file to stdout:

   nyl render apps.yaml

   For a targetless deterministic render, provide Kubernetes capabilities explicitly:

   nyl render --kube-version 1.31.0 --kube-api-versions v1,apps/v1 apps.yaml

   For target-aware rendering, scaffold a Cluster and target, update the Cluster’s capabilities, then select the target:

   git init
   nyl create cluster local --context kind-kind
   nyl capture cluster local
   nyl create target dev
   nyl render --target dev apps.yaml

   GitOps resource discovery follows Git visibility. Cluster creation records the context without contacting Kubernetes; nyl capture cluster performs the live capability refresh explicitly.

Tip

Every command takes the same path over the configuration in Git, so what you render here is what CI renders.

Project Structure

platform/
├── nyl.toml                  # Project configuration
├── applications/             # Application sources
├── config/
│   ├── clusters/             # Concrete clusters and render capabilities
│   ├── argocd-instances/     # Argo CD control planes and catalog defaults
│   ├── targets/              # Cluster-to-publication bindings
│   ├── repositories/         # Named Git coordinates
│   ├── projects/             # Argo CD project policy
│   └── application-groups/   # Application selection and lifecycle policy
├── components/               # Component definitions
│   └── v1.example.io/
│       └── MyApp/
│           ├── Chart.yaml
│           ├── values.yaml
│           ├── values.schema.json
│           └── templates/
│               └── deployment.yaml
└── charts/                   # Optional: additional Helm chart search path

Where to go next

Take what you need. If Kubernetes is all you deploy, you never need Orchestration.

Kubernetes GitOps

Publish plain YAML for Argo CD, Flux, or another reconciler.

CLI-First Workflows

Debugging, bootstrapping, testing, and direct cluster operations.

Component System

Map Kubernetes-style resources to Helm charts.

Configuration

Every `nyl.toml` setting.