CLI Overview

The kairos CLI is the primary interface for Substrate evaluation, trace management, scenario operations, and license management. Substrate is the on-premise KAIROS deployment.

Installation

The release packages the CLI for Debian Linux on x86-64. Install it from your release package or follow the installation guide.

Command Structure

kairos <command> [subcommand] [options]

kairos --help

Top-Level Commands

Command	Description
evaluate	Single-shot Substrate evaluation
observe	Live telemetry TUI dashboard (in the release package)
trace	Trace operations: export, diff, inspect, baseline, bundle, and more
scenario	Scenario operations: lint, manifest management
events	Event script operations: lint, inspect, diff
backtest	Score a trace against expected outcomes
policy	Validate or inspect a deployment policy
hitl	Human-in-the-loop coordinator and operator operations
cyber	Cybersecurity replay operations (in the release package)
robotics	Robotics validation and evidence operations (not in the release package)
fingerprint	Print machine fingerprint for license registration
activate	Install and validate a license file
license	License operations: status

Global Conventions

Output Formats

Many commands accept --format with two options:

Format	Description
json	Pretty-printed JSON (default)
table	Pretty-printed JSON

trace export is an exception: --format json prints compact JSON unless --pretty is set. --format table prints pretty-printed JSON.

Exit Codes

Code	Meaning
0	Command completed successfully
1	Runtime, input, or validation error
2	Recorded differences in comparison commands, or command-line usage error

A successful evaluate command can return a rejection verdict with exit code 0. Inspect the response to determine the verdict.

Errors normally go to stderr. license status --json reports an invalid license as JSON on stdout and exits 1.

stdin Support

evaluate reads the request from stdin when --request is omitted. trace diff requires two file paths and does not read stdin.

With request.json, artifact.json, policy.json, and a valid installed license, evaluate a request with:

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

License Commands

kairos fingerprint

Print the machine fingerprint for license registration.

kairos fingerprint

The command prints Machine fingerprint: <fingerprint>, a blank line, then this registration instruction:

Send this value to Ananke Labs to register this machine on your license.

To print JSON with fingerprint, hostname, and platform, run:

kairos fingerprint --json

kairos activate

Install and validate a license file.

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

To use a custom install location, run:

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)

Replace /path/to/license.key with the supplied license path. The command validates the license before copying it. It prints License valid, then Customer, License, Mode, Domains, Expires, and Installed, in that order.

kairos license status

Show the current license status.

kairos license status

To print JSON, run:

kairos license status --json

To select another license file, run:

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

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

For a valid license, text output starts with License status: VALID. The fields follow in this order: Mode, Customer, License ID, Tier, Domains, Expires, and Fingerprint. Evaluation licenses with 14 days or fewer remaining also print an expiry warning and a support contact line. JSON output includes status, mode, customer, licenseId, tier, domains, expiresAt, daysRemaining, fingerprint, and fingerprintMatch. For an invalid license, JSON output contains status: "INVALID" and error. Text output starts with License status: INVALID, followed by the error.

Scenario Commands

kairos scenario lint

Lint a scenario manifest for errors.

kairos scenario lint manifest.json

Use a scenario manifest JSON file for manifest.json. The command prints OK: <count> scenarios parsed from <path> to stderr. Duplicate IDs produce WARNING: duplicate scenario ID '<id>'. Invalid JSON prints FAIL: <error> and exits 1.

kairos scenario manifest

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

kairos scenario manifest show

This prints the embedded manifest as JSON. To print a custom manifest, run:

kairos scenario manifest show --manifest custom.json

To validate a manifest, run:

kairos scenario manifest validate manifest.json

On success, this prints Validation OK: <count> scenarios to stderr.

To compare manifests, run:

kairos scenario manifest diff a.json b.json

This prints JSON with countA, countB, onlyInA, onlyInB, common, and identical. Different manifests exit 2.

To create a JSON archive, run:

kairos scenario manifest pack create manifest.json --output archive.pack.json

This prints Packed <count> scenarios to <path> to stderr.

To validate an archive, run:

kairos scenario manifest pack validate archive.pack.json

On success, this prints Content: <count> scenarios, then Pack validation OK (version: <version>) to stderr. Validation checks the pack version, scenario parsing, and count. It does not verify the stored SHA-256 hash.

To compare archives, run:

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

This compares the stored hashes and prints versionA, versionB, scenariosA, scenariosB, hashMatch, and identical as JSON. Different hashes exit 2. Use existing manifests and archives for the example file names.

Command	Optional flags
manifest show	--manifest, --format json or --format table
manifest diff	--format json or --format table
manifest pack create	--version (default: 0.0.0)