CLI: observe

kairos observe launches a live terminal dashboard that runs a fly-by-wire session and displays real-time telemetry. It requires the tui feature flag at build time.

Build Requirement

cargo build -p kairos-cli --features tui --profile release-native

Usage

kairos observe \
  --scenario <scenario-id> \
  --artifact <artifact.json> \
  --policy <policy.json> \
  [options]

Flags

Required

Flag	Description
--scenario	Scenario ID to simulate
--artifact	Path to calibration artifact JSON
--policy	Path to deployment policy JSON

Optional

Flag	Default	Description
--manifest	Embedded	Path to scenario manifest (uses embedded scenarios if omitted)
--events	None	Path to EDMS event script JSON
--license	~/.kairos/license.key	Path to license file
--seed	From scenario	Seed override
--tick-rate	200	Simulation tick interval in milliseconds (50–2000)
--max-ticks	Unlimited	Maximum number of ticks to step
--alerts	Off	Enable acoustic alerts on threshold breach
--alert-threshold	0.8	Criticality threshold for acoustic alerts
--markers	auto	Chart marker style: braille, halfblock, or auto
--export-dir	None	Directory for snapshot exports (enables S keybinding)
--sentinel	Off	Enable Sentinel assessment panel
--hitl	Off	Activate HITL operator mode
--coordinator-url	http://127.0.0.1:8787	Coordinator service URL (used with --hitl)
--operator-key-id	Required with --hitl	Authority key ID for the operator

Examples

Basic observation

kairos observe \
  --scenario axelrod-tournament \
  --artifact artifact.json \
  --policy policy.json

Full featured

kairos observe \
  --scenario axelrod-tournament \
  --artifact artifact.json \
  --policy policy.json \
  --tick-rate 200 \
  --alerts \
  --alert-threshold 0.75 \
  --sentinel \
  --export-dir /tmp/snapshots

HITL operator mode

kairos observe \
  --scenario axelrod-tournament \
  --artifact artifact.json \
  --policy policy.json \
  --hitl \
  --coordinator-url http://127.0.0.1:8787 \
  --operator-key-id operator-1

Dashboard Features

Tabbed Actor Selection

Multi-actor scenarios show one tab per actor. Switch actors with number keys (1–9) or Tab/Shift+Tab. In HITL mode, actor selection follows the selected override request.

Gauges

Real-time gauges display:

• Severity — magnitude of detected instability
• Imminence — how soon the instability will manifest
• Risk — combined risk metric (inertia and optimized variants)
• Criticality — overall system criticality

Predictive Radar Chart

Shows a 70/30 temporal split with:

• Vertical T-Now separator
• Drift projection overlay ($\lambda = 0$)
• Optimal projection overlay ($\lambda = 1$)
• Timeline event markers

Falls back to a V1 history chart when projection data is unavailable.

Sentinel Assessment Panel

Enabled with --sentinel. Displays a rule-based structured assessment:

• Risk level: NOMINAL, ELEVATED, or CRITICAL
• Steps-to-impact urgency
• Path divergence analysis
• Upcoming events list

HITL Operator Panel

Enabled with --hitl. Provides an integrated operator interface:

• Lists pending override requests from the coordinator
• Background polling (3-second interval)
• Approve/deny with confirmation dialogs
• Telemetry focus follows selected request’s actor
• Connection status indicator

Physics Log

Immutable scrolling log of engine events, decisions, and state transitions.

Snapshot Export

When --export-dir is set, press S to export the current dashboard state as a JSON snapshot.

Keyboard Shortcuts

Key	Action
q / Q / Ctrl+C	Quit
Space	Pause / resume simulation
Tab	Select next actor (disabled in HITL mode)
Shift+Tab	Select previous actor (disabled in HITL mode)
1–9	Select actor by index (disabled in HITL mode)
S	Export snapshot (when --export-dir is set)

HITL-Specific Keys

Key	Action
Up / Down	Navigate override request list
Enter	Toggle detail view for selected request
A	Approve selected request (opens confirmation)
D	Deny selected request (opens confirmation)
R	Force refresh from coordinator
Y	Confirm action (in confirmation dialog)
N / Esc	Cancel action (in confirmation dialog)