Commands

Commands grouped by what they are for. Each page documents one command or a closely related pair.

Available Commands

• Project setup: create and check a project.
  • init - Initialize a Nyl project
  • create and delete - Add or remove GitOps resource source files
  • validate - Validate project configuration
  • schema - Generate project and resource schemas for editors and CI
• Project inputs: inspect resources and pin what rendering reads.
  • get and update - Inspect resources, capture cluster capabilities, and move source locks
  • vendor - Snapshot and verify remote renderer inputs
• Kubernetes Rendering: act on a cluster directly, through the shared rendering pipeline.
  • render - Render Kubernetes manifests
  • diff - Show diff between rendered manifests and cluster state
  • apply - Apply rendered manifests to the cluster
  • release - Inspect release history and roll back to a previous revision
• Kubernetes GitOps: render, compare, and publish a deployment target’s tree.
  • render-tree - Render a deployment target into a destination tree
  • diff-tree - Compare a target’s desired tree with its publication or a source revision
  • publish-tree - Publish a target’s tree to its branch with compare-and-swap
• CI integration: report results where reviewers look.
  • comment - Maintain sticky PR/MR comments on GitHub, GitLab, and Forgejo
• Orchestration (in development): manage environments’ state in Git.
  • build - Build an artifact from the current checkout without state writes
  • plan - Show what a reconcile would do, without writing anything
  • reconcile - Execute an environment’s ready units and record the results
  • status - Report each unit’s state from one snapshot of an environment’s state
  • verify - Check current receipts for drift and record the observations
  • teardown - Tear units down, or every unit, and confirm a publication’s removal
  • hold and resume - Freeze a unit so reconcile changes nothing about it, and lift the hold
  • recover - Clear a unit’s uncertain or failed condition, or accept a checkpointed result
  • exec - Run a held unit’s native tool with recorded repair context
  • state and lease - Create, move, forget, reset, restore, and delete an environment’s state; break a lost lease

Orchestration warnings and errors appear as separate blocks on stderr. Each block shows a headline, labelled details and actions when available, and a stable code. Table headings and diagnostic severity use terminal styling when color is enabled; the same information remains readable without color. JSON reports remain on stdout. A finding retains its complete code, message, and fix in JSON; optional title, details, and actions provide presentation fields for the same facts and remedies. For example, a status check against deleted state reports:

$ nyl status -e dev --color never
error  State for environment 'dev' was deleted

  Start over    nyl state init -e dev --fresh
  Decommission  remove Environment dev from source

  NYL-STATE-DELETED

Global Options

--quiet-unit-output hides public tool output from orchestration units while keeping their start/end messages. --unit-log-dir DIR appends masked unit logs to files, independently of console output. See Following execution for usage.

--verbose / -v

Enable verbose logging for debugging.

nyl --verbose validate
nyl -v init my-app --minimal

--color <COLOR>

Control when to use colored output. Accepts three values:

• auto (default) - Automatically detect if colors should be used based on TTY detection
• always - Always use colors, even when output is redirected to a file or pipe
• never - Never use colors

This applies to both:

• Colored output from commands (diffs, status indicators, etc.)
• Log messages from tracing (INFO, WARN, ERROR)

This flag is particularly useful when:

• Redirecting output to a file where ANSI color codes are not desired
• Working in environments where terminal color support is inconsistent
• Forcing colored output in CI/CD pipelines that support ANSI colors

# Disable colors when piping to a file
nyl --color never diff | tee output.txt

# Force colors in CI/CD
nyl --color always diff

# Auto-detect (default behavior)
nyl diff

--help / -h

Show help information for any command.

nyl --help
nyl create --help
nyl validate --help

--version / -V

Show the version of nyl.

nyl --version

• build builds a unit artifact locally or pushes it without orchestration state writes.