CLI Overview

The kairos CLI is the primary interface for Substrate evaluation, trace management, scenario operations, policy validation, and license management.

Installation

Build the CLI from the kairos-engine workspace:

# Standard CLI
cargo build -p kairos-cli --profile release-native

# CLI with the observe TUI dashboard
cargo build -p kairos-cli --features tui --profile release-native

The binary is placed at target/release-native/kairos. Add it to your PATH or install it to a standard location.

Command Structure

kairos <command> [subcommand] [options]

Top-Level Commands

Command	Description
`evaluate`	Single-shot Substrate evaluation
`observe`	Live telemetry TUI dashboard (requires `tui` feature)
`trace`	Trace operations: export, diff, inspect, baseline, bundle, and more
`scenario`	Scenario operations: lint, manifest management
`events`	Event script operations: lint, inspect, diff
`policy`	Deployment policy operations: validate, inspect
`hitl`	HITL coordinator and operator operations
`fingerprint`	Print machine fingerprint for license registration
`activate`	Install and validate a license file
`license`	License operations: status
`backtest`	Backtest operations: score traces against expected outcomes

Global Conventions

Output Formats

Many commands accept --format with two options:

Format	Description
`json`	JSON output (default)
`table`	Human-readable table format

Exit Codes

Code	Meaning
`0`	Success
`1`	Error (details in stderr)

stdin Support

Commands that accept file input (evaluate, trace diff, etc.) read from stdin when the file path is omitted. This enables piping:

cat request.json | kairos evaluate --config artifact.json --policy policy.json

License Commands

`kairos fingerprint`

Print the machine fingerprint for license registration.

kairos fingerprint          # Plain text output
kairos fingerprint --json   # JSON output

`kairos activate`

Install and validate a license file.

kairos activate --license /path/to/license.key
kairos activate --license /path/to/license.key --target /opt/kairos/license.key

Flag	Required	Description
`--license`	Yes	Path to the `.key` file from Ananke Labs
`--target`	No	Install location (default: `~/.kairos/license.key`)

`kairos license status`

Display the current license status.

kairos license status
kairos license status --json
kairos license status --license /opt/kairos/license.key

Flag	Required	Description
`--license`	No	Override license file path
`--json`	No	Output as JSON

Policy Commands

`kairos policy validate`

Validate a deployment policy file.

kairos policy validate policy.json

Checks JSON schema conformance, base policy signature, override constraints, and HITL configuration.

`kairos policy inspect`

Show the resolved deployment policy configuration.

kairos policy inspect policy.json

Displays the effective policy after applying operator overrides to the base policy.

Scenario Commands

`kairos scenario lint`

Lint a scenario manifest for errors.

kairos scenario lint manifest.json

`kairos scenario manifest`

Scenario manifest operations: show, validate, diff, pack.

kairos scenario manifest show                     # Show embedded manifest
kairos scenario manifest show --manifest custom.json
kairos scenario manifest validate manifest.json
kairos scenario manifest diff a.json b.json
kairos scenario manifest pack create manifest.json --output archive.tar
kairos scenario manifest pack validate archive.tar
kairos scenario manifest pack diff a.tar b.tar

Event Script Commands

`kairos events lint`

Lint an EDMS event script for errors.

kairos events lint events.json

`kairos events inspect`

Inspect an event script and print summary.

kairos events inspect events.json
kairos events inspect events.json --format table

`kairos events diff`

Diff two event scripts.

kairos events diff a.json b.json