# keryn knowledge run

Describes Keryn 0.5.2 and keryn-rules 0.8.0.

> keryn knowledge run: verify selected-source and assistant retrieval boundaries

Source: https://keryn.dev/docs/reference/cli/knowledge-run/

> **Caution: Next release: keryn knowledge run**
> On main; not in Keryn 0.5.2, the latest release.

Verify selected-source and assistant retrieval boundaries.

```text
keryn knowledge run <suite.json> --out <new-directory> --suite-sha256 <digest> [--timeout <seconds>] [--json]
```

## Options

```text
Usage: keryn ai-test validate <suite.json> [--json]
       keryn ai-test run <suite.json> --out <new-directory> [--timeout <seconds>] [--suite-sha256 <digest>] [--resume <receipt.json>] [--json]
       keryn ai-test packs [--json]
       keryn ai-test init <pack> --target <origin> --application <id> --revision <id> --out <new-directory>
       keryn ai-test verify <receipt.json> --suite <suite.json> --baseline <receipt.json> --baseline-suite <suite.json> --out <new-directory>
       keryn ai-test capture <capture.har> --target <url> --application <id> --revision <id> --out <new-directory> [--json]
  validate sends no requests. capture reads HAR locally and writes a redacted, non-executable draft; add reviewed routes,
  secret references, identity checks, positive controls and security assertions before producing a runnable suite.
  run sends bounded HTTP requests to the suite's declared origin. Credentials come from named environment variables.
  Authentication is verified before and after trials; failed controls, expired identities and unobservable assertions are inconclusive.
  --timeout is per request (default 30, max 300 seconds); the suite deadline is 300 seconds. Redirects are refused.
  --suite-sha256 pins original suite bytes (used by ci); a mismatch sends no requests.
  An actor may declare a session (keryn.dev/ai-session/v1): login with environment-referenced credentials, the token or cookie in one
  header, a bounded refresh on expiry or auth loss, the actor verified again after each refresh, and logout. Only replayable steps
  (GET, HEAD, OPTIONS, or replayable: true) are sent again after a refresh; others become blockers (exit 3).
  A run that stops early writes checkpoint.json (digests, the next step, secret names; no values); --resume <receipt.json> continues there.
  Artifacts: receipt.json, summary.md. Receipts omit request/response payloads and resolved credentials, retaining evidence hashes.
  Exit 0 assertions pass | 1 assertion violation | 2 invalid suite/options | 3 inconclusive | 4 execution failure.
  A test assertion failure is not by itself proof of exploitability; review the recorded checks and fixture contract.
```

## Examples

```sh
# Retain original suites and receipts for review.
keryn knowledge run suite.json --out out/run --suite-sha256 <digest>
```

## Exit codes

| Code | Meaning |
|---|---|
| 0 | pass |
| 1 | findings or a requested change gate |
| 2 | usage error or invalid input |
| 3 | incomplete or unknown completion |
| 4 | execution or normalization failure |
