Commands

Klyro has four commands. They share one versioned klyro.yaml source document: the same file you validate is the file you plan and generate from.

Command	Purpose	Writes files?
klyro create [DIR]	Collect selections and generate a complete project	Yes
klyro validate SPEC	Decode and resolve a specification	No
klyro plan SPEC --out DIR	Preview topology, artifacts, actions, and diffs	No
klyro generate SPEC --out DIR	Render and write the deployment project	Yes

validate, plan, and generate accept SPEC positionally or with --config <path>; both --config path and --config=path are supported, and supplying both forms is allowed only when they name the same path. --json emits machine-readable output without terminal decoration.

klyro create

Creates a complete project interactively using prompts:

• Prompts appear only when attached to an interactive terminal.
• Cancellation exits cleanly (code 130) without writing a partial project.
• Requires --name and --runtime in non-interactive use; optional selections include --memory, --interfaces, and model flags.
• Refuses to replace conflicting project files unless confirmed with --yes.
• Serializes its selections canonically into the output klyro.yaml.

klyro validate

Decodes and resolves a specification without generating anything:

• Distinguishes schema errors from compatibility errors.
• Reports structured diagnostics with stable codes; use --json for machine-readable output.
• Never writes files.

klyro plan

Resolves a valid specification and shows what generation would produce:

• Selected providers, chosen bindings, supporting services, required environment-variable names, ports, volumes, and configuration files.
• Every planned artifact with its target path, an action (create, overwrite, or skip), and a unified diff of intended content versus current on-disk state.
• Byte-stable output for identical input; read-only, always.

klyro generate

Renders artifacts and writes the project:

• Validates before writing; all failures happen before mutation.
• Copies the validated klyro.yaml source text into the output directory, preserving comments and line endings.
• Produces deterministic output for identical input.

Overwrite policy

All planned destinations are validated and inspected before the first write. The default policy refuses conflicts.

Policy	Behavior
default	Refuse conflicting destinations
--overwrite-owned	Replace only files carrying Klyro’s managed marker
--force	Replace every planned conflict

Unplanned files are never touched. Exact byte matches are skipped. A conflicting klyro.yaml is user-owned source, so replacing it requires an explicit policy rather than --overwrite-owned. See the klyro.yaml reference.

Exit codes

Code	Meaning
0	Success
1	Unexpected defect (details only with KLYRO_VERBOSE=1)
2	Invalid command, usage, or schema/configuration input
3	Unsupported or incompatible stack
4	Planning, rendering, unsafe-path, overwrite, or filesystem failure
5	Reserved for unavailable external tools or external validation failures
130	User cancellation

Interactive cancellation during create exits with 130 and leaves no partial project.

Operating generated projects

Generated Compose files are standard Docker Compose and require no Klyro daemon or hosted service; the operating steps are in the quickstart.