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

The command parses the JSON file as a vector of scenarios and reports any deserialization errors. It 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'

The command exits with 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. Both print pretty-printed JSON.

---

kairos scenario manifest validate

Validate a scenario manifest for structural integrity and required fields.

kairos scenario manifest validate scenarios.json

Validation checks:

1. The 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 with label 'Multi Actor' has empty id
  - Scenario 'multi-actor': duplicate agent ID 'alpha'

The command exits with code 1 on validation failure.

---

kairos scenario manifest diff

Compare two scenario manifests and report differences.

kairos scenario manifest diff reference.json comparison.json

Flag	Default	Description
--format	json	Output format: json or table. Both print pretty-printed JSON.

The command 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
}

If manifests differ, the command exits with code 2. If manifests are identical, the command exits with code 0.

---

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 command computes the SHA-256 hash of the original JSON file and stores it in sha256. pack diff compares these stored hashes. pack validate does not recompute the hash.

Output (success):

Packed 6 scenarios to scenarios.pack.json

---

kairos scenario manifest pack validate

Validate a packed scenario manifest archive.

kairos scenario manifest pack validate scenarios.pack.json

Validation checks:

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

Output (success):

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

The command exits with 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
}

The command compares the stored sha256 values only. If they differ, the command exits with code 2. If they match, the command exits with code 0.