# Explain a rule and read the docs offline

> Use keryn explain for what a rule says and the edge it sits on, and keryn docs for command help, exit codes, formats and the edge kinds, with no network.

Source: https://keryn.dev/docs/guides/explain-and-docs/

## Goal

Answer "what does this finding mean?" and "what does this flag do?" from the terminal, in the same words the website uses, without a network connection and without opening a browser.

## Before you start

- The Keryn CLI ([install](https://keryn.dev/docs/start/install/)). Both commands read from the package. They make no request.
- A rule id from a finding. `keryn scan . --verbose` prints it in brackets; the [rule catalog](https://keryn.dev/rules/) lists them all.

## 1. Explain a rule

```sh
keryn explain seceng.llm05.python-subprocess-shell-true
```

```text
seceng.llm05.python-subprocess-shell-true

subprocess with shell=True is risky if command text can be influenced by model, tool, or workflow output.

Severity     WARNING
Confidence   P1
FP risk      medium
Kind         vuln
Edge         calls (boundary: model->code)
Languages    python
Technology   github-actions
OWASP LLM    LLM05 Improper Output Handling; LLM06 Excessive Agency
OWASP AgenticASI05 Unexpected Code Execution; ASI02 Tool Misuse and Exploitation
CWE          CWE-78

Framework ids are references for readers who work in those frameworks, not a compliance claim.
```

What the lines say, and where the website says it too:

| Line | Meaning | Longer explanation |
|---|---|---|
| Severity | what the gate uses: ERROR, WARNING or INFO | [formats](https://keryn.dev/docs/reference/formats/) |
| Confidence, FP risk | how sure the rule's author is (P0 to P3) and how often it fires on code that is fine | [rule catalog](https://keryn.dev/rules/) |
| Edge, boundary | which relationship the rule inspects (`calls`) and which trust boundary it crosses (`model->code`) | [edge kinds](https://keryn.dev/docs/edges/edge-kinds/#calls), [trust boundaries](https://keryn.dev/docs/edges/trust-boundaries/#model-to-code) |
| OWASP, CWE | framework ids, for readers who work in them | [taxonomies](https://keryn.dev/taxonomies/) |

A rule's remediation and references are printed under these lines when it has them. The detection logic is never printed: no pattern, source or sink leaves the monorepo. For a script, `--json` prints the same fields as an object (`id`, `message`, `severity`, `confidence`, `edge`, `edgeBoundary`, `taxa`, `references`, ...).

A mistyped id exits 2 and suggests the nearest:

```sh
keryn explain seceng.llm05.python-subprocess
```

```text
keryn: error: no rule 'seceng.llm05.python-subprocess'; did you mean: seceng.llm05.python-subprocess-shell-true
```

Some entries in a scan's `--verbose` list, such as `seceng/shell_exec`, are findings from Keryn's data-flow engine rather than rule files, so they have no page to explain; the pattern rules that sit next to them do.

### Your own rules

`--rules` points `explain` at a rule file or a bundled pack, so a rule you wrote in [custom rules](https://keryn.dev/docs/guides/custom-rules/) explains itself the same way:

```yaml
rules:
  - id: acme.agent-without-max-turns
    languages: [python]
    severity: WARNING
    message: Runner.run is called without max_turns; bound the agent loop.
    patterns:
      - pattern: Runner.run(...)
      - pattern-not: Runner.run(..., max_turns=$N, ...)
```

```sh
keryn explain acme.agent-without-max-turns --rules rules/no-unbounded-agent.yml
```

```text
acme.agent-without-max-turns

Runner.run is called without max_turns; bound the agent loop.

Severity     WARNING
Languages    python
```

Add `metadata.edge`, `metadata.confidence` and `metadata.references` to your rule and they appear here.

## 2. Read the docs that ship in the CLI

```sh
keryn docs | head -8
```

```text
Keryn docs (offline pack 0.5.2, source cli-builtin)

Usage: keryn docs <topic>   |   keryn docs --list --json

  cmd-agents         usage of keryn agents
  cmd-ai-test        usage of keryn ai-test
  cmd-api            usage of keryn api
  cmd-application    usage of keryn application
```

With no topic it lists them. A topic is an id or a unique prefix. An ambiguous prefix (`cmd-s` matches several commands) names the candidates and exits 2, and so does an unknown topic:

```sh
keryn docs nope
```

```text
keryn: error: no docs topic 'nope' (try 'keryn docs --list')
```

Today the pack holds the command help (`cmd-<command>`), `commands`, `options` (the flags every scan command shares), `exit-codes`, `formats` and `edges` (the eight edge kinds). Topics print as Markdown, so they pipe into any pager or into an agent:

```sh
keryn docs edges | sed -n 1,3p
```

```text
# Edge kinds

Trust lives in relationships, so Keryn describes a finding by the edge it sits on. Each rule carries `metadata.edge`, one of the eight kinds below or `none`
```

Every page is checked against the pack's SHA-256 manifest before it is printed, so a damaged pack fails loudly. `keryn docs --list --json` is the machine-readable index, and `KERYN_DOCS_PACK=<directory>` reads another pack of the same format, such as one built from this site with `npm run docs-pack` in its repository.

## 3. Use them together

A finding says `Edge calls (boundary: model->code)`. `keryn docs edges` says what `calls` means, `keryn explain` says which rule, and the page for the [kind](https://keryn.dev/docs/edges/edge-kinds/#calls) and the [boundary](https://keryn.dev/docs/edges/trust-boundaries/#model-to-code) say what to do about it. The terminal gives you the definition and the website gives you the diagram; both come from the same source.

## What you just proved

The words in a finding are not a private vocabulary of the tool: each one (rule, edge, boundary, exit code) can be looked up from the thing you are holding, offline, with the same definition the docs use. That matters in the places where Keryn runs: a CI runner, an air-gapped network, a train.

## Next

- Write your own rule and explain it: [custom rules](https://keryn.dev/docs/guides/custom-rules/).
- Everything the CLI accepts: [CLI reference](https://keryn.dev/docs/reference/cli/).
- Run with no network at all: [air-gapped use](https://keryn.dev/docs/guides/air-gapped/).
