> ## Documentation Index
> Fetch the complete documentation index at: https://getquality.md/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI reference

> The qualitymd command-line interface that the /quality skill builds on.

The `/quality` skill drives the `qualitymd` CLI for you. This reference is for
when you want to run commands directly. It is generated from the CLI's own
command definitions, so it always matches the installed binary.

## Commands

| Command                | Description                                                   |
| ---------------------- | ------------------------------------------------------------- |
| `qualitymd init`       | Scaffold a starter QUALITY.md                                 |
| `qualitymd lint`       | Validate a QUALITY.md file                                    |
| `qualitymd model`      | Query a quality model's structure and canonical reference IDs |
| `qualitymd spec`       | Emit the QUALITY.md format specification                      |
| `qualitymd schema`     | Emit the companion JSON Schema for QUALITY.md frontmatter     |
| `qualitymd evaluation` | Work with QUALITY.md evaluation runs                          |
| `qualitymd version`    | Show structured qualitymd version metadata                    |
| `qualitymd update`     | Update the qualitymd CLI through its owning install channel   |
| `qualitymd status`     | Show a QUALITY.md workspace status snapshot                   |

## `qualitymd init`

Scaffold a starter QUALITY.md

```bash theme={null}
qualitymd init [path] [flags]
```

**Flags**

| Flag                      | Description                                                      |
| ------------------------- | ---------------------------------------------------------------- |
| `--force`                 | overwrite an existing file                                       |
| `--json`                  | emit a machine-readable JSON init receipt                        |
| `--minimal`               | write a minimal valid skeleton without the guided template prose |
| `--no-agent-instructions` | do not create or update agent instruction files                  |

**Examples**

```bash theme={null}
qualitymd init
qualitymd init docs/QUALITY.md
qualitymd init --minimal
qualitymd init --no-agent-instructions
qualitymd init - > QUALITY.md
qualitymd init --force
```

## `qualitymd lint`

Validate a QUALITY.md file

```bash theme={null}
qualitymd lint [path] [flags]
```

**Flags**

| Flag     | Description                              |
| -------- | ---------------------------------------- |
| `--fix`  | apply deterministic in-place repairs     |
| `--json` | emit a machine-readable JSON lint result |

**Examples**

```bash theme={null}
qualitymd lint
qualitymd lint docs/QUALITY.md
qualitymd lint --fix
qualitymd lint --json
```

## `qualitymd model`

Query a quality model's structure and canonical reference IDs

```bash theme={null}
qualitymd model
```

**Subcommands**

| Command                | Description                                       |
| ---------------------- | ------------------------------------------------- |
| `qualitymd model tree` | Render the model as a containment hierarchy       |
| `qualitymd model list` | Enumerate model elements with their canonical IDs |
| `qualitymd model get`  | Show one element's detail and immediate relations |

### `qualitymd model tree`

Render the model as a containment hierarchy

```bash theme={null}
qualitymd model tree [path] [flags]
```

**Flags**

| Flag      | Description                                                       |
| --------- | ----------------------------------------------------------------- |
| `--area`  | root the tree at a canonical area reference (area:\<path>)        |
| `--depth` | limit nesting depth; 0 emits only the rooted node (default: `-1`) |
| `--json`  | emit the tree as nested JSON                                      |

**Examples**

```bash theme={null}
qualitymd model tree
qualitymd model tree --area area:agent-harness
qualitymd model tree --depth 1 --json
```

### `qualitymd model list`

Enumerate model elements with their canonical IDs

```bash theme={null}
qualitymd model list [path] [flags]
```

**Flags**

| Flag     | Description                                          |
| -------- | ---------------------------------------------------- |
| `--area` | restrict output to one area's subtree (area:\<path>) |
| `--json` | emit the enumeration as a JSON array                 |
| `--type` | restrict output to kinds: area, factor, requirement  |

**Examples**

```bash theme={null}
qualitymd model list
qualitymd model list --type factor
qualitymd model list --area area:agent-harness --type requirement --json
```

### `qualitymd model get`

Show one element's detail and immediate relations

```bash theme={null}
qualitymd model get <id> [path] [flags]
```

**Flags**

| Flag     | Description                              |
| -------- | ---------------------------------------- |
| `--json` | emit the element detail as a JSON object |

**Examples**

```bash theme={null}
qualitymd model get area:root
qualitymd model get factor:client-app::performance
qualitymd model get requirement:agent-harness::has-tests --json
```

## `qualitymd spec`

Emit the QUALITY.md format specification

```bash theme={null}
qualitymd spec
```

**Examples**

```bash theme={null}
qualitymd spec
qualitymd spec | glow
qualitymd spec > SPECIFICATION.md
```

## `qualitymd schema`

Emit the companion JSON Schema for QUALITY.md frontmatter

```bash theme={null}
qualitymd schema
```

**Examples**

```bash theme={null}
qualitymd schema
qualitymd schema > quality.schema.json
```

## `qualitymd evaluation`

Work with QUALITY.md evaluation runs

```bash theme={null}
qualitymd evaluation
```

**Subcommands**

| Command                       | Description                                  |
| ----------------------------- | -------------------------------------------- |
| `qualitymd evaluation create` | Create a numbered evaluation run folder      |
| `qualitymd evaluation list`   | List evaluation runs                         |
| `qualitymd evaluation status` | Show whether an evaluation run is reportable |
| `qualitymd evaluation data`   | Work with evaluation structured data         |
| `qualitymd evaluation report` | Build evaluation reports                     |

### `qualitymd evaluation create`

Create a numbered evaluation run folder

```bash theme={null}
qualitymd evaluation create [model] [flags]
```

**Flags**

| Flag               | Description                                                    |
| ------------------ | -------------------------------------------------------------- |
| `--area`           | canonical area reference for the evaluation scope              |
| `--evaluation-dir` | override the model-relative evaluation directory               |
| `--factor`         | canonical factor reference for a scoped evaluation; repeatable |
| `--json`           | emit a machine-readable run creation receipt                   |
| `--model`          | QUALITY.md file to snapshot                                    |

### `qualitymd evaluation list`

List evaluation runs

```bash theme={null}
qualitymd evaluation list [flags]
```

**Flags**

| Flag               | Description                                               |
| ------------------ | --------------------------------------------------------- |
| `--evaluation-dir` | override the model-relative evaluation directory          |
| `--json`           | emit a machine-readable run list                          |
| `--model`          | QUALITY.md file that anchors evaluation history           |
| `--state`          | filter runs: all, reportable, incomplete (default: `all`) |

### `qualitymd evaluation status`

Show whether an evaluation run is reportable

```bash theme={null}
qualitymd evaluation status <run> [flags]
```

**Flags**

| Flag               | Description                                                          |
| ------------------ | -------------------------------------------------------------------- |
| `--evaluation-dir` | override the model-relative evaluation directory when using --latest |
| `--json`           | emit a machine-readable status document                              |
| `--latest`         | use the most recent evaluation run                                   |
| `--model`          | QUALITY.md file that anchors model-relative run paths                |

### `qualitymd evaluation data`

Work with evaluation structured data

```bash theme={null}
qualitymd evaluation data
```

**Subcommands**

| Command                             | Description                                              |
| ----------------------------------- | -------------------------------------------------------- |
| `qualitymd evaluation data set`     | Validate and persist a batch of evaluation JSON payloads |
| `qualitymd evaluation data list`    | List stored evaluation JSON payloads                     |
| `qualitymd evaluation data get`     | Print one stored evaluation JSON payload                 |
| `qualitymd evaluation data kinds`   | List evaluation data kinds                               |
| `qualitymd evaluation data example` | Print a complete evaluation example JSON payload         |
| `qualitymd evaluation data schema`  | Print the evaluation structured data JSON Schema         |
| `qualitymd evaluation data verify`  | Validate persisted evaluation JSON payloads              |

#### `qualitymd evaluation data set`

Validate and persist a batch of evaluation JSON payloads

```bash theme={null}
qualitymd evaluation data set <run> [flags]
```

**Flags**

| Flag               | Description                                                          |
| ------------------ | -------------------------------------------------------------------- |
| `--dry-run`, `-n`  | validate and report intended write without persisting                |
| `--evaluation-dir` | override the model-relative evaluation directory when using --latest |
| `--json`           | emit a machine-readable write receipt                                |
| `--latest`         | use the most recent evaluation run                                   |
| `--model`          | QUALITY.md file that anchors model-relative run paths                |

#### `qualitymd evaluation data list`

List stored evaluation JSON payloads

```bash theme={null}
qualitymd evaluation data list <run> [flags]
```

**Flags**

| Flag               | Description                                                          |
| ------------------ | -------------------------------------------------------------------- |
| `--evaluation-dir` | override the model-relative evaluation directory when using --latest |
| `--json`           | emit a machine-readable data list                                    |
| `--kind`           | filter by evaluation data kind                                       |
| `--latest`         | use the most recent evaluation run                                   |
| `--model`          | QUALITY.md file that anchors model-relative run paths                |

#### `qualitymd evaluation data get`

Print one stored evaluation JSON payload

```bash theme={null}
qualitymd evaluation data get <run> [flags]
```

**Flags**

| Flag               | Description                                                          |
| ------------------ | -------------------------------------------------------------------- |
| `--area`           | area ref for area-scoped payloads                                    |
| `--evaluation-dir` | override the model-relative evaluation directory when using --latest |
| `--factor`         | factor ref for factor-scoped payloads                                |
| `--json`           | not supported: data get already emits JSON                           |
| `--kind`           | evaluation data kind                                                 |
| `--latest`         | use the most recent evaluation run                                   |
| `--model`          | QUALITY.md file that anchors model-relative run paths                |
| `--requirement`    | requirement ref for requirement-scoped payloads                      |
| `--selector`       | optional sub-result selector                                         |

#### `qualitymd evaluation data kinds`

List evaluation data kinds

```bash theme={null}
qualitymd evaluation data kinds [flags]
```

**Flags**

| Flag     | Description                            |
| -------- | -------------------------------------- |
| `--json` | emit a machine-readable data kind list |

#### `qualitymd evaluation data example`

Print a complete evaluation example JSON payload

```bash theme={null}
qualitymd evaluation data example <kind> [flags]
```

**Flags**

| Flag     | Description                                    |
| -------- | ---------------------------------------------- |
| `--json` | not supported: data example already emits JSON |

#### `qualitymd evaluation data schema`

Print the evaluation structured data JSON Schema

```bash theme={null}
qualitymd evaluation data schema [kind] [flags]
```

**Flags**

| Flag     | Description                                   |
| -------- | --------------------------------------------- |
| `--json` | not supported: data schema already emits JSON |

#### `qualitymd evaluation data verify`

Validate persisted evaluation JSON payloads

```bash theme={null}
qualitymd evaluation data verify <run> [flags]
```

**Flags**

| Flag               | Description                                                          |
| ------------------ | -------------------------------------------------------------------- |
| `--evaluation-dir` | override the model-relative evaluation directory when using --latest |
| `--json`           | emit a machine-readable verification receipt                         |
| `--latest`         | use the most recent evaluation run                                   |
| `--model`          | QUALITY.md file that anchors model-relative run paths                |

### `qualitymd evaluation report`

Build evaluation reports

```bash theme={null}
qualitymd evaluation report
```

**Subcommands**

| Command                             | Description                            |
| ----------------------------------- | -------------------------------------- |
| `qualitymd evaluation report build` | Build deterministic evaluation reports |

#### `qualitymd evaluation report build`

Build deterministic evaluation reports

```bash theme={null}
qualitymd evaluation report build <run> [flags]
```

**Flags**

| Flag               | Description                                                          |
| ------------------ | -------------------------------------------------------------------- |
| `--evaluation-dir` | override the model-relative evaluation directory when using --latest |
| `--json`           | emit a machine-readable build receipt                                |
| `--latest`         | use the most recent evaluation run                                   |
| `--model`          | QUALITY.md file that anchors model-relative run paths                |

## `qualitymd version`

Show structured qualitymd version metadata

```bash theme={null}
qualitymd version [flags]
```

**Flags**

| Flag     | Description                            |
| -------- | -------------------------------------- |
| `--json` | emit machine-readable version metadata |

## `qualitymd update`

Update the qualitymd CLI through its owning install channel

```bash theme={null}
qualitymd update [flags]
```

**Flags**

| Flag      | Description                                                        |
| --------- | ------------------------------------------------------------------ |
| `--check` | check whether a newer CLI release is available without applying it |
| `--json`  | emit a machine-readable update result                              |

## `qualitymd status`

Show a QUALITY.md workspace status snapshot

```bash theme={null}
qualitymd status [path] [flags]
```

**Flags**

| Flag     | Description                                       |
| -------- | ------------------------------------------------- |
| `--json` | emit a machine-readable workspace status snapshot |

**Examples**

```bash theme={null}
qualitymd status
qualitymd status docs/QUALITY.md
qualitymd status --json
```