CLI: evaluate

kairos evaluate performs a single stateless Substrate evaluation. It loads a calibration artifact and deployment policy, validates the license, and evaluates a request JSON.

Usage

kairos evaluate \
  --config artifact.json \
  --policy policy.json \
  [--license license.key] \
  [--request request.json]

Flags

Flag	Required	Description
--config	Yes	Path to the calibration artifact JSON
--policy	Yes	Path to the deployment policy JSON
--license	No	Path to the license key file (default: ~/.kairos/license.key)
--request	No	Path to the request JSON (reads stdin if omitted)

Request Format

The request JSON must be an EvaluationRequest envelope:

{
  "envelopeVersion": 1,
  "requestId": "eval-001",
  "snapshot": {
    "timestamp": "2026-03-21T12:00:00.000Z",
    "metrics": {
      "primaryRiskMetric": 450.0,
      "primaryStabilityMetric": 72.0
    }
  }
}

The snapshot.metrics object must include the metric keys expected by your deployment’s calibration artifact.

Response

The command prints the EvaluationResponse as pretty-printed JSON to stdout:

{
  "envelopeVersion": 1,
  "requestId": "eval-001",
  "decision": "PASS",
  "reasonCode": "NONE",
  "mode": "state_gate",
  "policyVersion": 1,
  "adapterVersion": 1,
  "evaluation": {
    "currentGamma": 0.68,
    "gammaFloor": 0.20,
    "currentLambda": 0.89,
    "stability": 2.40,
    "predictedGamma": null
  },
  "escalation": null,
  "overrideOutcome": null,
  "timestamp": "2026-03-21T12:00:00.500Z"
}

stdin Usage

When --request is omitted, the command reads from stdin:

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

echo '{"envelopeVersion":1,"requestId":"r1","snapshot":{"timestamp":"2026-03-21T12:00:00Z","metrics":{"primaryRiskMetric":450,"primaryStabilityMetric":72}}}' \
  | kairos evaluate --config artifact.json --policy policy.json

Errors

Errors are printed to stderr with a non-zero exit code:

Error	Cause
failed to load calibration artifact	Invalid or missing artifact file
failed to load deployment policy	Invalid or missing policy file
failed to parse request JSON	Malformed request
License validation errors	Expired, missing, or fingerprint mismatch

Notes

• evaluate performs a single stateless evaluation.
• For live dashboards and stateful telemetry, use kairos observe.