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",
    "signature": null,
    "metrics": {
      "capabilityIndex": 450.0,
      "alignmentScore": 72.0
    }
  },
  "action": null,
  "actorId": null,
  "overrideToken": null
}

The snapshot.metrics must include all metrics referenced by the calibration artifact’s scaling functions.

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"
}

HITL Override Tokens

kairos evaluate transparently supports HITL override tokens. No special flags are needed — the overrideToken field in the request JSON is optional. When present, HITL verification is invoked automatically.

# Evaluate with an override token included in the request
kairos evaluate \
  --config artifact.json \
  --policy policy.json \
  --request request-with-token.json

The response will include an overrideOutcome field showing whether the token was Applied or Rejected.

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":{"capabilityIndex":450,"alignmentScore":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 uses SubstrateRuntime (stateless). It does not maintain engine state between calls.
• Action gating and hazard gating are not available — those require SubstrateSession, available via kairos observe or the native library API.
• The action field in the request is accepted but ignored in state-gate mode.