CLI: trace

kairos trace provides a comprehensive set of trace management commands for exporting, comparing, inspecting, and packaging simulation traces.

Subcommands

Subcommand	Description
export	Export a trace from a scenario simulation
diff	Diff two trace files
inspect	Inspect a trace file and print summary
baseline	Generate baseline traces for one or more scenarios
hash	Compute SHA-256 hash of a file
bundle	Batch export traces with manifest
manifest	Output the embedded scenario manifest
trend	Per-step trend metrics for a trace
report	Generate a formatted trace report
suite	Trace suite operations (create, compare, lint, validate, pack)

Every subcommand with --format accepts json (the default) or table. Both values print the same pretty-printed JSON. Status messages go to stderr, and data goes to stdout.

---

kairos trace export

Export a trace from a scenario simulation.

kairos trace export \
  --scenario standard \
  --steps 200 \
  [--seed 1207] \
  [--output trace.json] \
  [--format json] \
  [--manifest manifest.json] \
  [--events events.json] \
  [--pretty]

kairos trace export --scenario standard --output trace.json

Flag	Default	Description
--scenario	Required	Scenario ID to simulate
--steps	200	Number of simulation steps
--seed	From scenario	Override the scenario seed
--output / -o	stdout	Output file path
--format	json	Output format: json or table. Without --pretty, json prints compact JSON and table prints pretty-printed JSON.
--manifest	Embedded	Path to a custom scenario manifest
--events	None	Path to an EDMS event script
--pretty	Off	Pretty-print JSON output

With --output, the command writes the trace to the file and prints Trace written to <path> to stderr. Without it, the trace goes to stdout.

---

kairos trace diff

Compare two trace files for differences. The first operand is the expected baseline and the second is the actual trace. Both file paths are required. trace diff does not read stdin.

kairos trace diff expected.json actual.json

Flag	Default	Description
--epsilon	1e-6	Finite, nonnegative absolute tolerance for floating-point fields. 0 or -0 compares the decoded values exactly. A negative value must use attached form, for example --epsilon=-0.
--format	json	Output format

Use trace diff to find the first difference between two traces, for example two exports of the same scenario, seed, configuration, events, and moves. Equal means every field of the current trace schema matches after decoding. Integers, strings, booleans and presence match exactly, and floating-point values match within the absolute epsilon. The decoder ignores unknown fields during decoding.

When the traces are equal, the command prints Traces are equal (epsilon=<epsilon>) to stderr. On divergence, it prints the divergence result to stdout.

The divergence result’s field is an absolute RFC 6901 JSON Pointer, for example /steps/0/agents/1/pairwiseGamma/a~1b~0c. The expected value comes from the first operand and actual from the second.

After argument parsing, trace diff exits with code 0 when equal, 1 on a load, comparison or input error, and 2 on divergence. A command-line usage error also exits with code 2 before the comparison runs, so exit 2 alone is ambiguous.

Equality covers the decoded trace values. Byte identity, trace origin and integrity, and agreement across runtimes or platforms require separate checks.

---

kairos trace inspect

Inspect a trace file and print summary.

kairos trace inspect trace.json --summary

Flag	Default	Description
--summary	Off	Print a compact summary instead of full details
--format	json	Output format: json or table

---

kairos trace baseline

Generate baseline traces for one or more scenarios.

# Specific scenarios
kairos trace baseline --scenarios standard,axelrod-tournament --steps 200 --output-dir baselines/

# All scenarios
kairos trace baseline --all --steps 200 --output-dir baselines/

Flag	Default	Description
--scenarios	None	Comma-separated scenario IDs
--all	Off	Generate baselines for all scenarios
--steps	200	Number of simulation steps
--output-dir	.	Output directory for baseline files
--manifest	Embedded	Path to a custom scenario manifest

The command writes one <scenario-id>.trace.json file per scenario. It prints Baseline: <path> for each file and Generated <count> baseline(s) at the end, both to stderr.

---

kairos trace hash

Compute the SHA-256 hash of a file.

kairos trace hash trace.json

The command prints the hexadecimal SHA-256 digest of the file bytes to stdout.

---

kairos trace bundle

Batch export traces with a manifest.

kairos trace bundle --scenarios standard,axelrod --steps 200 --output-dir bundle/
kairos trace bundle --all --steps 200 --output-dir bundle/

Flag	Default	Description
--scenarios	None	Comma-separated scenario IDs
--all	Off	Bundle all scenarios
--steps	200	Number of simulation steps
--output-dir	.	Output directory
--manifest	Embedded	Path to a custom scenario manifest

The command writes one <scenario-id>.trace.json file per scenario and a bundle.json manifest with the fields scenarios, steps, and files. It prints Bundle written to <output-dir> to stderr.

---

kairos trace manifest

Output the embedded or custom scenario manifest.

kairos trace manifest --manifest custom.json

Flag	Default	Description
--manifest	Embedded	Path to a custom manifest
--format	json	Output format: json or table

---

kairos trace trend

Compute per-step trend metrics for a trace.

kairos trace trend trace.json

Flag	Default	Description
--format	json	Output format: json or table

---

kairos trace report

Generate a formatted trace report.

kairos trace report trace.json

Flag	Default	Description
--format	json	Output format: json or table

---

kairos trace suite

Suite operations manage collections of traces for regression testing.

kairos trace suite create

Create a baseline suite.

kairos trace suite create --steps 200 --output-dir suite/

Flag	Default	Description
--steps	200	Number of simulation steps
--output-dir	.	Output directory
--manifest	Embedded	Path to a custom scenario manifest

The command writes one <scenario-id>.trace.json file per scenario. It prints Suite baseline: <path> for each file and Suite created with <count> scenarios at the end, both to stderr.

kairos trace suite compare

Compare current traces against a baseline suite. Each baseline is the expected operand and the current trace is the actual operand.

kairos trace suite compare --baseline-dir suite/ --steps 200

Flag	Default	Description
--baseline-dir	Required	Directory containing baseline traces
--steps	200	Number of simulation steps
--epsilon	1e-6	Finite, nonnegative absolute tolerance for floating-point fields. 0 or -0 compares the decoded values exactly. A negative value must use attached form, for example --epsilon=-0.
--manifest	Embedded	Path to a custom scenario manifest

For each scenario, the command prints one line to stderr: PASS <scenario-id>, FAIL <scenario-id>: <field> at step Some(<index>), or SKIP <scenario-id>: <error>. A divergence outside the step list prints at step None. It ends with <pass-count> passed, <fail-count> failed. When a comparison fails, it also prints a JSON array to stdout with one { "scenarioId", "details" } object per failure.

The command reports every baseline load error as SKIP, including missing, unreadable, malformed, or wrong-version files. An empty or all-skipped suite can exit 0 without comparing any trace.

suite compare exits with code 0 when all performed comparisons are equal, 2 for recorded divergences, and 1 for propagated errors. Command-line usage errors also exit with code 2 before the comparison runs. Read the comparison results and SKIP messages alongside the exit code to establish which baselines were compared.

kairos trace suite lint

Check that a suite directory holds a <scenario-id>.trace.json file for every embedded scenario.

kairos trace suite lint suite/

The command prints Suite lint: OK (<count> traces found). If files are missing, it lists them and exits with code 1. It checks against the embedded scenarios only, so a suite created with --manifest can report missing traces.

kairos trace suite validate

Validate that each suite trace for an embedded scenario loads as a trace.

kairos trace suite validate suite/

The command prints OK <file> or ERR <file>: <error> per trace, then All <count> traces valid. If any trace fails, it prints <count> validation errors and exits with code 1.

kairos trace suite pack

Pack operations for suite archives. An archive is a single JSON document that holds every <scenario-id>.trace.json file of the embedded scenarios, each with its SHA-256 hash and size.

# Create archive
kairos trace suite pack create suite/ --output suite.pack.json

# Validate archive
kairos trace suite pack validate suite.pack.json

# Diff two archives
kairos trace suite pack diff a.pack.json b.pack.json

pack create prints Packed <count> traces to <path>.

pack validate checks that the archive version is 1, that scenarioCount matches the number of files, and that each file’s content parses as a trace. It prints OK <file> or ERR <file>: <error> per file, then Pack validation OK: <count> files. It does not verify the stored SHA-256 hashes. On failure it exits with code 1.

pack diff compares file names and the stored SHA-256 hashes. It prints a JSON object with filesA, filesB, onlyInA, onlyInB, contentDiffers, and identical, and exits with code 2 when the archives differ.