# kosa8 validate oq

Run an Operational Qualification protocol in a clone of a validated snapshot

## Usage

```
kosa8 oq SNAPSHOT --protocol FILE
```

Runs each step of a declared test protocol (YAML or JSON: a command, where
to run it, and the expected exit code and output) inside a sandbox restored
from SNAPSHOT under a new name, so the validated state is never modified.
Records every step's result with timestamps and output digests, the
protocol file by digest, and the snapshot's seal as verified at restore.
The clone is removed afterwards unless --keep-clone.

A protocol (docs/design/gxp-validation.md has the full format):

  id: OQ-STATS-001
  version: "1.0"
  title: R environment operational qualification
  image: r-base:4.4.1
  steps:
    - id: OQ-01
      title: R reports the validated version
      requirement: URS-12
      run: [R, --version]
      expect: {exit: 0, stdout_regex: 'R version 4\.4\.1'}

## Flags

| Flag | Type | What it does | Default |
|---|---|---|---|
| `--html` | bool | also render RECORD.html |  |
| `--keep-clone` | bool | leave the clone the steps ran in, for investigating a failure |  |
| `--out, -o` | string | record package: .tar for a tar, else a directory (default <RECORD-ID>.tar) |  |
| `--protocol, -p` | string | the OQ protocol to execute (YAML or JSON) |  |
| `--signer` | string | printed name of the package signer |  |
| `--signer-key` | string | sign the package with this Ed25519 key file instead of the machine's key |  |

## Example

```
  kosa8 validate oq stats-validated --protocol oq-stats.yaml --out oq-2026-09.tar
```

---
Source: https://docs.kosa8.com/reference/validate-oq/