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] \
  [--hmac-secret <secret>]

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)
--hmac-secret	No	HMAC shared secret for snapshot signature verification

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 that your deployment’s calibration artifact expects.

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
  },
  "escalation": null,
  "overrideOutcome": null,
  "timestamp": "2026-03-21T12:00:00.500Z"
}

stdin Usage

When you omit --request, 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

The command prints errors 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 read request file: <path>	The --request file cannot be read
failed to read request from stdin	No readable request on stdin
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.