CLI: scenario

kairos scenario manages scenario manifests — the JSON files that define simulation configurations with agents, seeds, and parameters.

Subcommands

Subcommand	Description
lint	Lint a scenario manifest for parsing errors
manifest show	Output the scenario manifest
manifest validate	Validate manifest structure and required fields
manifest diff	Compare two manifests
manifest pack create	Create a packed manifest archive
manifest pack validate	Validate a packed archive
manifest pack diff	Compare two packed archives

---

kairos scenario lint

Lint a scenario manifest for parsing errors and duplicate IDs.

kairos scenario lint scenarios.json

Parses the JSON file as a vector of scenarios and reports any deserialization errors. Warns on duplicate scenario IDs.

Output (success):

OK: 6 scenarios parsed from scenarios.json

Output (duplicates):

OK: 6 scenarios parsed from scenarios.json
WARNING: duplicate scenario ID 'standard'

Exit code 1 on parse failure.

---

kairos scenario manifest show

Output the scenario manifest in the requested format.

# Show embedded manifest (compiled into the binary)
kairos scenario manifest show

# Show a custom manifest
kairos scenario manifest show --manifest custom-scenarios.json

# Output format
kairos scenario manifest show --format json

Flag	Default	Description
--manifest	Embedded	Path to a custom manifest JSON
--format	json	Output format (json or table)

---

kairos scenario manifest validate

Validate a scenario manifest for structural integrity and required fields.

kairos scenario manifest validate scenarios.json

Validation checks:

1. File parses as valid JSON
2. Each scenario has a non-empty id
3. Each scenario has a non-empty label
4. Agent IDs within each scenario are unique

Output (success):

Validation OK: 6 scenarios

Output (failure):

Validation failed:
  - scenario at index 2: empty id
  - scenario 'multi-actor': duplicate agent ID 'alpha'

Exit code 1 on validation failure.

---

kairos scenario manifest diff

Compare two scenario manifests and report differences.

kairos scenario manifest diff reference.json comparison.json [--format json]

Uses set operations on scenario IDs to identify additions, removals, and common scenarios.

Output:

{
  "countA": 6,
  "countB": 8,
  "onlyInA": ["deprecated-scenario"],
  "onlyInB": ["new-scenario-1", "new-scenario-2", "new-scenario-3"],
  "common": 5,
  "identical": false
}

Exit code 2 if manifests differ, 0 if identical.

---

kairos scenario manifest pack create

Create a packed scenario manifest archive with versioning and an integrity hash.

kairos scenario manifest pack create scenarios.json \
  --output scenarios.pack.json \
  --version 1.2.0

Flag	Default	Description
--output	Required	Output archive path
--version	0.0.0	Version string for the archive

Packed format:

{
  "version": "1.2.0",
  "packVersion": 1,
  "scenarioCount": 6,
  "sha256": "a7f8b9c3d4e5...",
  "content": [ ... ]
}

The SHA-256 hash is computed from the original JSON data for integrity verification.

---

kairos scenario manifest pack validate

Validate a packed scenario manifest archive.

kairos scenario manifest pack validate scenarios.pack.json

Validation checks:

1. File is valid JSON
2. packVersion is 1
3. content parses as a valid scenario array
4. scenarioCount matches actual content count

Output (success):

Pack validation OK (version: 1.2.0)
Content: 6 scenarios

Exit code 1 on validation failure.

---

kairos scenario manifest pack diff

Compare two packed scenario manifest archives.

kairos scenario manifest pack diff a.pack.json b.pack.json

Output:

{
  "versionA": "1.0.0",
  "versionB": "1.2.0",
  "scenariosA": 6,
  "scenariosB": 8,
  "hashMatch": false,
  "identical": false
}

Exit code 2 if archives differ (hash mismatch), 0 if identical.