CLI: observe

kairos observe launches a live terminal dashboard that runs a fly-by-wire session and displays real-time telemetry.

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

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

Dashboard Features

Tabbed Actor Selection

Multi-actor scenarios show one tab per actor. Switch actors with number keys (1–9) or Tab/Shift+Tab.

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 current telemetry, recent history, and projected risk movement when projection data is available.

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

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
Shift+Tab	Select previous actor
1–9	Select actor by index
S	Export snapshot (when --export-dir is set)