CLI Overview

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

Installation

Install the CLI from your release package or follow the installation guide.

Command Structure

kairos <command> [subcommand] [options]

Top-Level Commands

Command	Description
`evaluate`	Single-shot Substrate evaluation
`observe`	Live telemetry TUI dashboard
`trace`	Trace operations: export, diff, inspect, baseline, bundle, and more
`scenario`	Scenario operations: lint, manifest management
`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`	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

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