# 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](/configuration/klyro-yaml/#source-ownership).

## 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](/getting-started/quickstart/#5-run-the-stack).