---
title: "@kovojs/cli"
description: "Command-line interface for the Kovo toolchain. Generated from the shared command manifest and public TypeScript source."
order: 9
---

# @kovojs/cli

Command-line interface for the Kovo toolchain. Generated from the shared
`@kovojs/cli` command manifest (`packages/cli/src/commands-manifest.ts`) and the
package's public TypeScript source. Do not edit by hand.

Run `kovo` with no arguments to list the available commands:

```sh
kovo: add, audit, build, check, compile, db, dev, docs, doctor, explain, export, fix, incident, mcp, test, update-docs
```

## Commands

### kovo add

Copy public @kovojs/ui component source into an application.

```sh
usage: kovo add --list | kovo add <component...> [--out <dir>] [--dry-run] [--install <auto|never>]
```

| Flag | Description |
| --- | --- |
| `<component...>` | One or more component catalog names. |
| `--out <dir>` | Destination for copied component source. Default: src/components/ui. |
| `--list` | List the exact copy-in component registry. |
| `--dry-run` | Plan without filesystem or process writes. |
| `--install <auto|never>` | Choose automatic dependency installation or no install. Default: auto. |

**Examples**

```sh
kovo add button
```

```sh
kovo add button card --out src/components/ui
```

### kovo audit

Run security and access audits over an app graph.

```sh
usage: kovo audit [--fail-on-findings] [graph.json]
```

| Flag | Description |
| --- | --- |
| `--fail-on-findings` | Exit 1 when the audit finds issues. |

**Examples**

```sh
kovo audit
```

```sh
kovo audit --fail-on-findings graph.json
```

### kovo doctor

Check local toolchain, package, config, database, and cache coherence.

```sh
usage: kovo doctor [root] [--fix] [--format <human|json|github>]
```

| Flag | Description |
| --- | --- |
| `--fix` | Apply only framework-classified safe repairs. |
| `--format <human|json|github>` | Select human, JSON, or GitHub diagnostic output. Default: human. |

**Examples**

```sh
kovo doctor
```

```sh
kovo doctor --format json
```

```sh
kovo doctor --fix
```

### kovo build

Prove and build an authored Kovo app for deployment.

```sh
usage: kovo build <app-module> [--out <dir>] [--preset <name>] [--check] [--no-cache] [--format <human|json|github>]
```

| Flag | Description |
| --- | --- |
| `--out <dir>` | Output directory for production artifacts. Default: dist. |
| `--preset <name>` | Select the deployment preset. |
| `--check` | Run every preflight without promoting output. |
| `--no-cache` | Disable build analysis caches. |
| `--format <human|json|github>` | Select human, JSON, or GitHub diagnostic output. Default: human. |

**Examples**

```sh
kovo build ./src/app.tsx --out dist
```

```sh
kovo build ./src/app.tsx --check
```

### kovo check

Run consistency, security, environment, and advisory verification.

```sh
usage: kovo check [--no-cache] [--format <human|json|github>] | kovo check source [app-module] [--no-cache] [--format <human|json|github>] | kovo check source [app-module] --watch [--no-cache] --format <json> | kovo check lifecycle [--format <human|json|github>] | kovo check endpoint-posture [--format <human|json|github>] | kovo check [optimistic|coverage|endpoint-posture|sources-sinks] [graph.json] [--artifact <graph.json>] [--format <human|json|github>] | kovo check env [deployment.json] [--format <human|json|github>] | kovo check advisories [graph.json] [--feed <url|file>] [--attestation <url|file>] [--state <file>] [--severity-floor <low|moderate|high|critical>] [--format <human|json|github>]
```

| Flag | Description |
| --- | --- |
| `source` | Derive proof from current authored source. |
| `lifecycle` | Verify the pnpm dependency lifecycle policy. |
| `endpoint-posture` | Run the framework-owned endpoint posture suite. |
| `optimistic|coverage|endpoint-posture|sources-sinks` | Select one focused graph-verification family. |
| `env` | Probe deployment environment obligations. |
| `advisories` | Check authenticated Kovo security advisories. |
| `--no-cache` | Disable source-analysis caches. |
| `--watch` | Keep one foreground source-check session open for revisions. |
| `--feed <url|file>` | Override the default HTTPS advisory feed. |
| `--attestation <url|file>` | Use an explicit Sigstore attestation bundle. |
| `--state <file>` | Override the local advisory epoch/equivocation state file. Default: .kovo/advisory-state.json. |
| `--severity-floor <low|moderate|high|critical>` | Set the blocking advisory severity floor. Default: high. |
| `--format <human|json|github>` | Select human, JSON, or GitHub diagnostic output. Default: human. |
| `--artifact <graph.json>` | Inspect the explicitly named completed build graph. |

**Examples**

```sh
kovo check
```

```sh
kovo check source ./src/app.tsx --no-cache
```

```sh
kovo check source --watch --format json
```

```sh
kovo check lifecycle
```

```sh
kovo check coverage graph.json
```

```sh
kovo check coverage --artifact dist/.kovo/graph.json
```

```sh
kovo check env deployment.json
```

```sh
kovo check advisories .kovo/graph.json
```

### kovo compile

Emit compiler-owned artifacts without importing compiler internals.

```sh
usage: kovo compile component <source.tsx> --out <artifact.tsx> [--file-name <name>] [--check] [--fixpoint] [--render-equivalence] [--registry-facts <json>] [--query-shape-facts <json>] [--facts-out <json>] [--emit-client-files] [--allow-diagnostic <code>]
       kovo compile route <source.tsx> --out <artifact.tsx> [--file-name <name>] [--artifact-file-name <name>] [--rewrite <Local=specifier>] [--facts-out <json>] [--check]
       kovo compile graph <input.json> --out <graph.json> [--check]
       kovo compile mutation-inputs <source.ts> --out <facts.json> [--file-name <name>] [--check]
       kovo compile drizzle-static <input.json> --out <facts.json> [--check]
       kovo compile drizzle-optimistic <input.json> --out <artifact.ts> [--facts-out <json>] [--check]
       kovo compile package-css <package> --out <file.css> [--entry <source.ts>] [--check]
```

| Flag | Description |
| --- | --- |
| `component` | Lower one authored component. |
| `route` | Lower one authored route. |
| `graph` | Compile a graph input artifact. |
| `mutation-inputs` | Extract mutation-input facts. |
| `drizzle-static` | Derive static Drizzle facts. |
| `drizzle-optimistic` | Derive a Drizzle optimistic transform. |
| `package-css` | Extract CSS for a public component package. |
| `--out <path>` | Artifact path to write or verify. |
| `--file-name <name>` | Logical source file name used in diagnostics. |
| `--artifact-file-name <name>` | Logical generated route artifact name. |
| `--check` | Verify current output instead of writing. |
| `--fixpoint` | Assert the lowered component is a fixpoint. |
| `--render-equivalence` | Assert authored/lowered render parity. |
| `--registry-facts <json>` | Read component registry facts from JSON. |
| `--query-shape-facts <json>` | Read query-shape facts from JSON. |
| `--facts-out <json>` | Write compiler-derived facts as JSON. |
| `--emit-client-files` | Emit/check component client artifacts. |
| `--allow-diagnostic <code>…` | Allow one registered diagnostic code. Repeatable. |
| `--rewrite <Local=specifier>…` | Rewrite one route component import. Repeatable. |
| `--entry <source.ts>` | Source entry used for component-prefix discovery. |

**Examples**

```sh
kovo compile component src/cart.tsx --out dist/cart.tsx --check
```

```sh
kovo compile route src/app.tsx --out dist/app.kovo-route.tsx
```

```sh
kovo compile package-css @kovojs/ui --entry src/app.ts --out dist/ui.css
```

### kovo db

Provision, migrate, generate, or verify a Kovo database.

```sh
usage: kovo db provision|migrate|generate|check [--schema <module>] [--migrations <dir>] [--driver <pglite|pg|node-postgres>] [--database-url <url>] [--admin-database-url <url>] [--system-database-url <url>] [--data-dir <dir>] [--reader-role <role>] [--writer-role <role>]
```

| Flag | Description |
| --- | --- |
| `provision|migrate|generate|check` | Select the database lifecycle action. |
| `--schema <module>` | Schema module path. Default: src/schema.ts. |
| `--migrations <dir>` | Directory of reviewed SQL migrations. Default: migrations. |
| `--driver <pglite|pg|node-postgres>` | Select the database driver. |
| `--database-url <url>` | Least-privilege runtime database URL. |
| `--admin-database-url <url>` | Privileged setup/check URL. |
| `--system-database-url <url>` | Least-privilege system/check URL. |
| `--data-dir <dir>` | PGlite development data directory. |
| `--reader-role <role>` | Reader database role. |
| `--writer-role <role>` | Writer database role. |

**Examples**

```sh
kovo db provision --schema src/schema.ts
```

```sh
kovo db check --driver pglite
```

### kovo dev

Start the bootstrap-first Kovo development server.

```sh
usage: kovo dev <app-module> [--root <dir>] [--config <file>] [--host <host>] [--port <port>] [--strict-port] [--mode <mode>] [--debug]
```

| Flag | Description |
| --- | --- |
| `--root <dir>` | Project root. Default: .. |
| `--config <file>` | Restricted authored client-plugin config. |
| `--host <host>` | Vite listen host. |
| `--port <port>` | Vite listen port. |
| `--strict-port` | Fail instead of selecting another occupied port. |
| `--mode <mode>` | Vite mode. Default: development. |
| `--debug` | Show verbose Vite development logs. |

**Examples**

```sh
kovo dev ./src/app.tsx
```

```sh
kovo dev ./src/app.tsx --port 4173 --strict-port
```

### kovo docs

Search the exact version-matched local Kovo documentation snapshot.

```sh
usage: kovo docs <task> [--limit <count>] [--format <human|json>]
```

| Flag | Description |
| --- | --- |
| `--limit <count>` | Maximum number of authenticated local results. Default: 5. |
| `--format <human|json>` | Select human or machine-readable output. Default: human. |

**Examples**

```sh
kovo docs quickstart
```

```sh
kovo docs "authenticated mutation" --limit 3 --format json
```

### kovo explain

Render stable proof facts for a subject or security review.

```sh
usage: kovo explain component|mutation|query|page|context|task <target> [--optimistic] [--layouts] [graph.json] [--artifact <graph.json>] [--format <human|json|github>]
       kovo explain document [graph.json] [--artifact <graph.json>] [--format <human|json|github>]
       kovo explain sources-sinks [graph.json] [--artifact <graph.json>] [--format <human|json|github>]
       kovo explain tasks [graph.json] [--artifact <graph.json>] [--format <human|json|github>]
       kovo explain agent [graph.json] [--artifact <graph.json>] [--format <human|json|github>]
       kovo explain grants [graph.json] [--artifact <graph.json>] [--format <human|json|github>]
       kovo explain endpoints [graph.json] [--artifact <graph.json>] [--format <human|json|github>]
       kovo explain revealed [graph.json] [--artifact <graph.json>] [--format <human|json|github>]
       kovo explain trust [graph.json] [--artifact <graph.json>] [--format <human|json|github>]
       kovo explain capabilities [graph.json] [--artifact <graph.json>] [--format <human|json|github>]
       kovo explain cookies [graph.json] [--artifact <graph.json>] [--format <human|json|github>]
       kovo explain authorization [graph.json] [--artifact <graph.json>] [--format <human|json|github>]
       kovo explain access [--fail-on-findings] [graph.json] [--artifact <graph.json>] [--format <human|json|github>]
       kovo explain unguarded [--fail-on-findings] [graph.json] [--artifact <graph.json>] [--format <human|json|github>]
       kovo explain unscoped [--fail-on-findings] [graph.json] [--artifact <graph.json>] [--format <human|json|github>]
       kovo explain auth-lifecycle [--format <human|json|github>]
       kovo explain model-boundaries [--format <human|json|github>]
       kovo explain attest <url> --artifact <graph.json> --trust-anchor <sha256:fingerprint> [--escape-reviews <reviews.json>] [--escape-census-reviews <reviews.json>] [--format <human|json|github>]
```

| Flag | Description |
| --- | --- |
| `component|mutation|query|page|context|task` | Select a graph subject kind. |
| `document` | Explain the framework-owned document shell. |
| `sources-sinks` | Print the source/sink inventory. |
| `tasks` | List durable-task facts and composition edges. |
| `agent` | Print model/tool effect closures by integrity level. |
| `grants` | Print compiler-derived grant and attenuation facts. |
| `endpoints` | Audit every machine-ingress surface. |
| `revealed` | List confidentiality reveals and their proof grade. |
| `trust` | List explicit trust escape hatches. |
| `capabilities` | List held capabilities and closed paths. |
| `cookies` | List cookie posture and downgrade findings. |
| `authorization` | Compare app guard facts and Postgres policies. |
| `access` | Review producer-owned access decisions. |
| `unguarded` | Audit handlers reachable without a guard. |
| `unscoped` | Audit owner data reached without owner scope. |
| `auth-lifecycle` | Print the Better Auth lifecycle contract. |
| `model-boundaries` | Print bounded-model assumptions. |
| `attest` | Attest a live deployment URL. |
| `--optimistic` | Include optimistic-update detail. |
| `--layouts` | Include the page layout chain. |
| `--fail-on-findings` | Exit 1 when an audit reports findings. |
| `--artifact <graph.json>` | Use the explicitly named build graph. |
| `--trust-anchor <sha256:fingerprint>` | Verify with the named SHA-256 trust anchor. |
| `--escape-reviews <reviews.json>` | Read signed escape-obligation reviews. |
| `--escape-census-reviews <reviews.json>` | Read signed escape-census reviews. |
| `--format <human|json|github>` | Select human, JSON, or GitHub diagnostic output. Default: human. |

**Examples**

```sh
kovo explain component Cart graph.json
```

```sh
kovo explain capabilities
```

```sh
kovo explain access --fail-on-findings
```

### kovo export

Export a Kovo app as static hosting output.

```sh
usage: kovo export <app-module> [--vite] [--root <dir>] [--out <dir>] [--origin <url>] [--manifest <file> --dist <dir>] [--asset-base <path>] [--skip-non-exportable]
```

| Flag | Description |
| --- | --- |
| `--vite` | Load the app through Vite SSR. |
| `--root <dir>` | Project root for Vite loading. |
| `--out <dir>` | Static export output directory. Default: dist. |
| `--origin <url>` | Absolute canonical origin. |
| `--manifest <file>` | Vite manifest to copy assets from. |
| `--dist <dir>` | Vite output directory containing manifest assets. |
| `--asset-base <path>` | URL path prefix for exported assets. |
| `--skip-non-exportable` | Skip non-exportable routes. |

**Examples**

```sh
kovo export ./src/app.ts --out dist
```

### kovo fix

Apply only compiler-proven safe TSX/JSX rewrites.

```sh
usage: kovo fix format [source-or-directory] [--check] | kovo fix <source.tsx|source.jsx> [--check] | kovo fix api-v1 [source-or-directory] --check | kovo fix api-v1 [source-or-directory] --write | kovo fix --cost-report
```

| Flag | Description |
| --- | --- |
| `format` | Format the project or named authored paths. |
| `api-v1` | Migrate the checked public API v1 batch. |
| `--check` | Report safe rewrites without writing. |
| `--cost-report` | Measure safe-vs-escape edit cost. |
| `--write` | Apply the complete API migration transaction. |

**Examples**

```sh
kovo fix src/components/cart.tsx
```

```sh
kovo fix format src
```

```sh
kovo fix api-v1 --check
```

```sh
kovo fix --cost-report
```

### kovo incident

Scope an advisory over a tamper-evident security-event export.

```sh
usage: kovo incident scope <advisory.json> --events <security-events.json>
```

| Flag | Description |
| --- | --- |
| `scope` | Evaluate the finite advisory decision-site predicate. |
| `--events <security-events.json>` | Bounded security-event export to inspect. |

**Examples**

```sh
kovo incident scope advisory.json --events security-events.json
```

### kovo mcp

Serve the finite Kovo MCP protocol over stdio.

```sh
usage: kovo mcp
```

**Examples**

```sh
kovo mcp
```

### kovo test

Run app tests with Kovo runtime ordering established first.

```sh
usage: kovo test [file] [--coverage] [--update] [--pass-with-no-tests] [--reporter <reporter>] [--test-name-pattern <pattern>]
```

| Flag | Description |
| --- | --- |
| `--coverage` | Collect test coverage. |
| `--update` | Update accepted test snapshots. |
| `--pass-with-no-tests` | Succeed when no tests are selected. |
| `--reporter <reporter>` | Select a supported test reporter. |
| `--test-name-pattern, -t <pattern>` | Run tests matching one name pattern. |

**Examples**

```sh
kovo test
```

```sh
kovo test src/app.test.ts
```

```sh
kovo test --coverage
```

### kovo update-docs

Refresh version-matched agent-readable Kovo documentation.

```sh
usage: kovo update-docs
```

**Examples**

```sh
kovo update-docs
```

## Programmatic API

The `@kovojs/cli` package also exposes a small one-shot semantic command and in-process
verifier surface. Callers name command concepts rather than argv flags. The diagnostic
construction and transport layers remain framework-internal (SPEC.md §11.3-§11.4). This
reference is
generated from `packages/cli/src/api.ts`.

### `@kovojs/cli`

**Task:** Semantic command execution and in-process graph verifiers behind the kovo CLI.

Source: [`packages/cli/src/api.ts`](https://github.com/kovojs/kovo/blob/main/packages/cli/src/api.ts)

#### Values

##### `kovoCheck` {#kovocheck}

Run the `kovo check` verifier in-process against an extracted graph.

Reports the consistency and exhaustiveness findings of SPEC.md §11.4: touch-graph
diagnostics, optimistic exhaustiveness (KV310), update coverage (KV311), fixpoint
and render-equivalence invariants, and the unguarded/unscoped audits. The
optional `family` selects the `optimistic`, `coverage`, `endpoint-posture`,
or `sources-sinks` slice (default `all`).
Returns the stable `kovo-check/v1` text plus an exit code that is non-zero when
any error-severity finding is present (SPEC.md §1.1 proof claims).

**Signature**

```ts
function kovoCheck(
  input: KovoCheckInput,
  options: { family?: KovoCheckFamily; paranoidStaticAdvisory?: boolean } = {},
): KovoCheckResult;
```

##### `kovoExplain` {#kovoexplain}

Run the `kovo explain` verifier in-process against an extracted graph.

Prints the stable `kovo-explain/v1` graph view selected by `options`: a single
component, mutation, query, or page subject; the `endpoints` machine-ingress
audit; or an access audit (SPEC.md §5.3 and §11.4).
The printed format is stable so agents and graph queries can answer intent-level
questions over it (SPEC.md §1.1 proof claims). Returns the text plus an exit
code that is non-zero only when an audit ran with `failOnFindings` and findings
were present.

**Signature**

```ts
function kovoExplain(input: KovoExplainInput, options: KovoExplainOptions): KovoCheckResult;
```

##### `runKovoCommand` {#runkovocommand}

Run the same command dispatcher as the `kovo` executable and return its exit
code from a semantic command request. Programmatic callers name command
concepts (`out`, `preset`), while only the bin adapter handles argv spellings
(`--out`, `--preset`). The call writes the command's normal stdout/stderr and
resolves after one-shot output is complete. Long-lived `dev` and `mcp`
processes remain executable-only until Kovo exposes an explicit
abort/disposal contract.

Commands that evaluate authored modules establish the same irreversible
compiler-realm lock as the executable before dispatch (SPEC.md §5.2 and §6.6).

**Signature**

```ts
async function runKovoCommand(
  request: KovoSemanticCommandRequest,
): Promise<KovoCommandExitCode>;
```

##### `KOVO_DIAGNOSTIC_VERSION` {#kovodiagnosticversion}

Stable wire version accepted by Kovo's public human, JSON, and GitHub renderers.

**Signature**

```ts
const KOVO_DIAGNOSTIC_VERSION = 'kovo-diagnostic/v1' as const;
```

#### Supporting types

##### `KovoCliDiagnosticCode` {#kovoclidiagnosticcode}

Finite framework-owned code vocabulary for CLI/process facts.

**Signature**

```ts
type KovoCliDiagnosticCode = keyof typeof CLI_DIAGNOSTIC_DEFINITIONS;
```

##### `KovoDiagnosticCategory` {#kovodiagnosticcategory}

Stable categories used to classify CLI process behavior.

**Signature**

```ts
type KovoDiagnosticCategory = 'build' | 'config' | 'proof' | 'runtime' | 'usage';
```

##### `KovoDiagnosticCommandResult` {#kovodiagnosticcommandresult}

Existing command result carried intact beside the shared diagnostics.

**Signature**

```ts
interface KovoDiagnosticCommandResult {
  readonly command: string;
  readonly exitCode: 0 | 1 | 2;
  readonly protocol: string;
  readonly text: string;
}
```

##### `KovoDiagnosticEnvelope` {#kovodiagnosticenvelope}

Serialized `kovo-diagnostic/v1` envelope emitted by machine-readable adapters.

**Signature**

```ts
interface KovoDiagnosticEnvelope {
  readonly diagnostics: readonly KovoDiagnosticRecord[];
  /** Present when a command adapter also preserves its existing fact protocol. */
  readonly result?: KovoDiagnosticCommandResult;
  readonly version: typeof KOVO_DIAGNOSTIC_VERSION;
}
```

##### `KovoDiagnosticFormat` {#kovodiagnosticformat}

Presentation adapters supported by {@link formatKovoDiagnostics}.

**Signature**

```ts
type KovoDiagnosticFormat = 'github' | 'human' | 'json';
```

##### `KovoDiagnosticRecord` {#kovodiagnosticrecord}

One registry-authenticated, transport-neutral diagnostic record.

`KV###` records can only be projected from an exact core-registry object. CLI/process records
can only be minted by the private finite registry above. The serialized fields are evidence,
not authority: copies and cross-realm lookalikes are never accepted by local renderers.

**Signature**

```ts
interface KovoDiagnosticRecord {
  readonly category: KovoDiagnosticCategory;
  readonly code: DiagnosticCode | KovoCliDiagnosticCode;
  readonly help?: string;
  readonly message: string;
  /**
   * Stable redacted runtime fact; raw server causes are deliberately absent.
   *
   * The public wire shape is declared here so consumers never need a core-internal import.
   */
  readonly runtime?: {
    readonly correlationId: string;
    readonly code:
      | 'KTB001'
      | 'KTB002'
      | 'KTB003'
      | 'KTB004'
      | 'KTB005'
      | 'KTB006'
      | 'KTB007'
      | 'KTB008';
    readonly operation:
      | 'app-request'
      | 'client-module'
      | 'error-shell'
      | 'mutation-handler'
      | 'mutation-render'
      | 'mutation-response-policy'
      | 'mutation-stream'
      | 'no-js-mutation-handler'
      | 'query-endpoint'
      | 'route-page'
      | 'route-render'
      | 'task-runner'
      | 'task-runtime-startup';
    readonly remediation: string;
    readonly safeCause:
      | 'client-module-resolution-failed'
      | 'error-shell-render-failed'
      | 'handler-execution-failed'
      | 'request-dispatch-failed'
      | 'response-policy-failed'
      | 'response-render-failed'
      | 'runtime-startup-failed'
      | 'task-execution-failed';
    readonly schema: 'kovo.trusted-boundary-failure/v1';
    readonly source?: {
      readonly end: number;
      readonly file: string;
      readonly start: number;
    };
    readonly sourceKind?: 'config' | 'source';
  };
  readonly severity: DiagnosticSeverity;
  readonly source?: KovoDiagnosticSourceAnchor;
  readonly version: typeof KOVO_DIAGNOSTIC_VERSION;
}
```

##### `KovoDiagnosticSourceAnchor` {#kovodiagnosticsourceanchor}

Exact source/configuration anchor using zero-based UTF-16 offsets and an exclusive end.

A zero-width range is the insertion point for a missing configuration value; this lets a
first-run failure name the file that must change without pretending nonexistent bytes were
authored.

**Signature**

```ts
interface KovoDiagnosticSourceAnchor {
  readonly end: number;
  readonly file: string;
  readonly start: number;
}
```

##### `ExplainKind` {#explainkind}

The kind of graph subject a targeted `kovo explain` describes — a component,
request context, mutation, query, page, or durable task (SPEC.md §5.3/§9.6).

**Signature**

```ts
type ExplainKind = 'component' | 'context' | 'mutation' | 'page' | 'query' | 'task';
```

##### `KovoAccessExplainOptions` {#kovoaccessexplainoptions}

`kovo explain access` options: emit the producer-owned access-decision
ledger from graph `access` facts (SPEC.md §10.2/§11.3).

**Signature**

```ts
interface KovoAccessExplainOptions {
  failOnFindings?: boolean;
  view: 'access';
}
```

##### `KovoAgentExplainOptions` {#kovoagentexplainoptions}

`kovo explain agent`: print compiler-derived model/tool effect closures by integrity.

**Signature**

```ts
interface KovoAgentExplainOptions {
  view: 'agent';
}
```

##### `KovoAuthLifecycleExplainOptions` {#kovoauthlifecycleexplainoptions}

`kovo explain auth-lifecycle`: print Better Auth ownership and explicit non-claims.

**Signature**

```ts
interface KovoAuthLifecycleExplainOptions {
  view: 'auth-lifecycle';
}
```

##### `KovoAuthorizationExplainOptions` {#kovoauthorizationexplainoptions}

`kovo explain authorization`: print honest guard/RLS non-correspondence records.

**Signature**

```ts
interface KovoAuthorizationExplainOptions {
  view: 'authorization';
}
```

##### `KovoCheckFamily` {#kovocheckfamily}

Check family selector accepted by {@link kovoCheck} and `kovo check`.

**Signature**

```ts
type KovoCheckFamily =
  | 'all'
  | 'coverage'
  | 'endpoint-posture'
  | 'optimistic'
  | 'sources-sinks';
```

##### `KovoCheckInput` {#kovocheckinput}

Opaque graph input accepted by `kovoCheck`.

Kovo validates this value at runtime before reading graph fields, so the
public CLI facade does not expose the internal verifier graph declarations
(SPEC.md §11.4; rules/api-surface.md recursive publicness).

**Signature**

```ts
type KovoCheckInput = unknown;
```

##### `KovoCheckResult` {#kovocheckresult}

Result of a `kovoCheck`/`kovoExplain` run: the stable verifier output text and
a process exit code (0 success, 1 failure) matching what the `kovo` bin would
emit (SPEC.md §11.4 verification surface; §1.1 proof claims).

**Signature**

```ts
interface KovoCheckResult {
  readonly diagnostics?: readonly KovoDiagnosticRecord[];
  exitCode: 0 | 1;
  output: string;
}
```

##### `KovoCommandExitCode` {#kovocommandexitcode}

Stable process exit codes returned by {@link runKovoCommand}.

**Signature**

```ts
type KovoCommandExitCode = 0 | 1 | 2;
```

##### `KovoDocumentExplainOptions` {#kovodocumentexplainoptions}

`kovo explain document` options: emit the framework-owned document shell
source/sink row plus any document-owned trust escape facts in the optional
extracted graph (SPEC.md §9.5; plans/structured-document.md).

**Signature**

```ts
interface KovoDocumentExplainOptions {
  view: 'document';
}
```

##### `KovoEndpointExplainOptions` {#kovoendpointexplainoptions}

`kovo explain endpoints` options: emit the stable machine-ingress audit table
of every declared endpoint, webhook, file/stream route, and dynamic ingress
surface (SPEC.md §11.4; plans/sources-sinks.md Phase 3).

**Signature**

```ts
interface KovoEndpointExplainOptions {
  view: 'endpoints';
}
```

##### `KovoExplainInput` {#kovoexplaininput}

Opaque graph input accepted by `kovoExplain`.

Kovo validates this value at runtime before reading graph fields, so the
public CLI facade does not expose the internal verifier graph declarations
(SPEC.md §11.4; rules/api-surface.md recursive publicness).

**Signature**

```ts
type KovoExplainInput = unknown;
```

##### `KovoExplainOptions` {#kovoexplainoptions}

Options selecting which `kovo explain` view `kovoExplain` produces. The
discriminant is shared by the programmatic API and the CLI's literal
subcommand grammar (SPEC.md §5.3 and §11.4).

**Signature**

```ts
type KovoExplainOptions =
  | KovoAccessExplainOptions
  | KovoAuthLifecycleExplainOptions
  | KovoAuthorizationExplainOptions
  | KovoAgentExplainOptions
  | { view: 'capabilities' }
  | { view: 'cookies' }
  | KovoDocumentExplainOptions
  | KovoEndpointExplainOptions
  | KovoGrantExplainOptions
  | { view: 'model-boundaries' }
  | KovoRevealedExplainOptions
  | KovoSourcesSinksExplainOptions
  | KovoTasksExplainOptions
  | KovoTargetExplainOptions
  | { view: 'trust' }
  | KovoUnguardedExplainOptions
  | KovoUnscopedExplainOptions;
```

##### `KovoGrantExplainOptions` {#kovograntexplainoptions}

`kovo explain grants`: print the compiler-derived finite grant model (SPEC §10.3).

**Signature**

```ts
interface KovoGrantExplainOptions {
  view: 'grants';
}
```

##### `KovoRevealedExplainOptions` {#kovorevealedexplainoptions}

`kovo explain revealed` options: emit every declared confidentiality reveal,
labeling proof-grade server projections separately from audit-grade arbitrary
function reveals (SPEC.md §1.1/§2; plans/secure-by-construction.md Phase 1).

**Signature**

```ts
interface KovoRevealedExplainOptions {
  view: 'revealed';
}
```

##### `KovoSourcesSinksExplainOptions` {#kovosourcessinksexplainoptions}

`kovo explain sources-sinks` options: emit the stable Phase 1 repository
source/sink inventory (SPEC.md §5.3; plans/sources-sinks.md Phase 1).

**Signature**

```ts
interface KovoSourcesSinksExplainOptions {
  view: 'sources-sinks';
}
```

##### `KovoTasksExplainOptions` {#kovotasksexplainoptions}

`kovo explain tasks` options: emit durable task nodes plus statically discovered composition
edges from task bodies (SPEC §9.6 and §11.4).

**Signature**

```ts
interface KovoTasksExplainOptions {
  view: 'tasks';
}
```

##### `KovoTargetExplainOptions` {#kovotargetexplainoptions}

Targeted `kovo explain` options: describe one graph subject of the given `kind`
and `target`, optionally including optimistic transform coverage for mutations
(SPEC.md §5.3).

**Signature**

```ts
interface KovoTargetExplainOptions {
  layouts?: boolean;
  optimistic?: boolean;
  target: string;
  view: ExplainKind;
}
```

##### `KovoUnguardedExplainOptions` {#kovounguardedexplainoptions}

`kovo explain unguarded` options: audit every mutation, route, and query
reachable without an `authed` guard, optionally failing when findings exist
(SPEC.md §11.4).

**Signature**

```ts
interface KovoUnguardedExplainOptions {
  failOnFindings?: boolean;
  view: 'unguarded';
}
```

##### `KovoUnscopedExplainOptions` {#kovounscopedexplainoptions}

`kovo explain unscoped` options: audit every query or write touching an
owner-annotated domain without an owner scope, optionally failing when findings
exist (SPEC.md §11.4).

**Signature**

```ts
interface KovoUnscopedExplainOptions {
  failOnFindings?: boolean;
  view: 'unscoped';
}
```

##### `KovoSemanticCommandRequest` {#kovosemanticcommandrequest}

Precise programmatic command union accepted by `runKovoCommand`.

This source is generated from `command-schema.ts`; run
`pnpm generate:cli-command-request` after changing the semantic command AST.
Forms, arguments, options, enum literals, repeats, and boolean polarity are
schema-owned. Argv flag spellings are deliberately absent. Long-lived
Long-lived command forms stay executable-only until they have an explicit
programmatic abort/disposal contract.

**Signature**

```ts
type KovoSemanticCommandRequest =
  | {
      readonly arguments: { readonly [key: PropertyKey]: never };
      readonly command: 'add';
      readonly form: 'list';
      readonly options: {
        readonly list: true;
      };
    }
  | {
      readonly arguments: {
        readonly components: readonly [
          (
            | 'accordion'
            | 'alert'
            | 'alert-dialog'
            | 'autocomplete'
            | 'avatar'
            | 'badge'
            | 'breadcrumb'
            | 'button'
            | 'card'
            | 'checkbox'
            | 'checkbox-group'
            | 'collapsible'
            | 'combobox'
            | 'command'
            | 'context-menu'
            | 'dialog'
            | 'disclosure'
            | 'drawer'
            | 'dropdown-menu'
            | 'field'
            | 'hover-card'
            | 'kbd'
            | 'menubar'
            | 'meter'
            | 'navigation-menu'
            | 'number-field'
            | 'otp-field'
            | 'popover'
            | 'progress'
            | 'radio-group'
            | 'scroll-area'
            | 'select'
            | 'separator'
            | 'sheet'
            | 'skeleton'
            | 'slider'
            | 'switch'
            | 'table'
            | 'tabs'
            | 'toast'
            | 'toggle'
            | 'toggle-group'
            | 'toolbar'
            | 'tooltip'
          ),
          ...(
            | 'accordion'
            | 'alert'
            | 'alert-dialog'
            | 'autocomplete'
            | 'avatar'
            | 'badge'
            | 'breadcrumb'
            | 'button'
            | 'card'
            | 'checkbox'
            | 'checkbox-group'
            | 'collapsible'
            | 'combobox'
            | 'command'
            | 'context-menu'
            | 'dialog'
            | 'disclosure'
            | 'drawer'
            | 'dropdown-menu'
            | 'field'
            | 'hover-card'
            | 'kbd'
            | 'menubar'
            | 'meter'
            | 'navigation-menu'
            | 'number-field'
            | 'otp-field'
            | 'popover'
            | 'progress'
            | 'radio-group'
            | 'scroll-area'
            | 'select'
            | 'separator'
            | 'sheet'
            | 'skeleton'
            | 'slider'
            | 'switch'
            | 'table'
            | 'tabs'
            | 'toast'
            | 'toggle'
            | 'toggle-group'
            | 'toolbar'
            | 'tooltip'
          )[],
        ];
      };
      readonly command: 'add';
      readonly form: 'components';
      readonly options?: {
        readonly out?: string;
        readonly dryRun?: boolean;
        readonly install?: 'auto' | 'never';
      };
    }
  | {
      readonly arguments: {
        readonly graph?: string;
      };
      readonly command: 'audit';
      readonly form: 'audit';
      readonly options?: {
        readonly failOnFindings?: boolean;
      };
    }
  | {
      readonly arguments: {
        readonly root?: string;
      };
      readonly command: 'doctor';
      readonly form: 'doctor';
      readonly options?: {
        readonly fix?: boolean;
        readonly format?: 'human' | 'json' | 'github';
      };
    }
  | {
      readonly arguments: {
        readonly appModule: string;
      };
      readonly command: 'build';
      readonly form: 'build';
      readonly options?: {
        readonly out?: string;
        readonly preset?: 'node' | 'vercel' | 'cloudflare';
        readonly check?: boolean;
        readonly cache?: boolean;
        readonly format?: 'human' | 'json' | 'github';
      };
    }
  | {
      readonly arguments: { readonly [key: PropertyKey]: never };
      readonly command: 'check';
      readonly form: 'source-default';
      readonly options?: {
        readonly cache?: boolean;
        readonly format?: 'human' | 'json' | 'github';
      };
    }
  | {
      readonly arguments: {
        readonly appModule?: string;
      };
      readonly command: 'check';
      readonly form: 'source';
      readonly options?: {
        readonly cache?: boolean;
        readonly format?: 'human' | 'json' | 'github';
      };
    }
  | {
      readonly arguments: { readonly [key: PropertyKey]: never };
      readonly command: 'check';
      readonly form: 'lifecycle';
      readonly options?: {
        readonly format?: 'human' | 'json' | 'github';
      };
    }
  | {
      readonly arguments: { readonly [key: PropertyKey]: never };
      readonly command: 'check';
      readonly form: 'endpoint-posture-suite';
      readonly options?: {
        readonly format?: 'human' | 'json' | 'github';
      };
    }
  | {
      readonly arguments: {
        readonly family?: 'optimistic' | 'coverage' | 'endpoint-posture' | 'sources-sinks';
        readonly graph?: string;
      };
      readonly command: 'check';
      readonly form: 'graph';
      readonly options?: {
        readonly format?: 'human' | 'json' | 'github';
        readonly artifact?: string;
      };
    }
  | {
      readonly arguments: {
        readonly deployment?: string;
      };
      readonly command: 'check';
      readonly form: 'environment';
      readonly options?: {
        readonly format?: 'human' | 'json' | 'github';
      };
    }
  | {
      readonly arguments: {
        readonly graph?: string;
      };
      readonly command: 'check';
      readonly form: 'advisories';
      readonly options?: {
        readonly feed?: string;
        readonly attestation?: string;
        readonly state?: string;
        readonly severityFloor?: 'low' | 'moderate' | 'high' | 'critical';
        readonly format?: 'human' | 'json' | 'github';
      };
    }
  | {
      readonly arguments: {
        readonly source: string;
      };
      readonly command: 'compile';
      readonly form: 'component';
      readonly options: {
        readonly out: string;
        readonly fileName?: string;
        readonly check?: boolean;
        readonly fixpoint?: boolean;
        readonly renderEquivalence?: boolean;
        readonly registryFacts?: string;
        readonly queryShapeFacts?: string;
        readonly factsOut?: string;
        readonly emitClientFiles?: boolean;
        readonly allowDiagnostic?: readonly string[];
      };
    }
  | {
      readonly arguments: {
        readonly source: string;
      };
      readonly command: 'compile';
      readonly form: 'route';
      readonly options: {
        readonly out: string;
        readonly fileName?: string;
        readonly artifactFileName?: string;
        readonly check?: boolean;
        readonly factsOut?: string;
        readonly rewrite?: readonly string[];
      };
    }
  | {
      readonly arguments: {
        readonly input: string;
      };
      readonly command: 'compile';
      readonly form: 'graph';
      readonly options: {
        readonly out: string;
        readonly check?: boolean;
      };
    }
  | {
      readonly arguments: {
        readonly source: string;
      };
      readonly command: 'compile';
      readonly form: 'mutation-inputs';
      readonly options: {
        readonly out: string;
        readonly fileName?: string;
        readonly check?: boolean;
      };
    }
  | {
      readonly arguments: {
        readonly input: string;
      };
      readonly command: 'compile';
      readonly form: 'drizzle-static';
      readonly options: {
        readonly out: string;
        readonly check?: boolean;
      };
    }
  | {
      readonly arguments: {
        readonly input: string;
      };
      readonly command: 'compile';
      readonly form: 'drizzle-optimistic';
      readonly options: {
        readonly out: string;
        readonly check?: boolean;
        readonly factsOut?: string;
      };
    }
  | {
      readonly arguments: {
        readonly package: string;
      };
      readonly command: 'compile';
      readonly form: 'package-css';
      readonly options: {
        readonly out: string;
        readonly check?: boolean;
        readonly entry?: string;
      };
    }
  | {
      readonly arguments: {
        readonly action: 'provision' | 'migrate' | 'generate' | 'check';
      };
      readonly command: 'db';
      readonly form: 'db';
      readonly options?: {
        readonly schema?: string;
        readonly migrations?: string;
        readonly driver?: 'pglite' | 'pg' | 'node-postgres';
        readonly databaseUrl?: string;
        readonly adminDatabaseUrl?: string;
        readonly systemDatabaseUrl?: string;
        readonly dataDir?: string;
        readonly readerRole?: string;
        readonly writerRole?: string;
      };
    }
  | {
      readonly arguments: {
        readonly task: string;
      };
      readonly command: 'docs';
      readonly form: 'docs';
      readonly options?: {
        readonly limit?: number;
        readonly format?: 'human' | 'json';
      };
    }
  | {
      readonly arguments: {
        readonly kind: 'component';
        readonly target: string;
        readonly graph?: string;
      };
      readonly command: 'explain';
      readonly form: 'target';
      readonly options?: {
        readonly optimistic?: false;
        readonly layouts?: false;
        readonly artifact?: string;
        readonly format?: 'human' | 'json' | 'github';
      };
    }
  | {
      readonly arguments: {
        readonly kind: 'mutation';
        readonly target: string;
        readonly graph?: string;
      };
      readonly command: 'explain';
      readonly form: 'target';
      readonly options?: {
        readonly optimistic?: boolean;
        readonly layouts?: false;
        readonly artifact?: string;
        readonly format?: 'human' | 'json' | 'github';
      };
    }
  | {
      readonly arguments: {
        readonly kind: 'query';
        readonly target: string;
        readonly graph?: string;
      };
      readonly command: 'explain';
      readonly form: 'target';
      readonly options?: {
        readonly optimistic?: false;
        readonly layouts?: false;
        readonly artifact?: string;
        readonly format?: 'human' | 'json' | 'github';
      };
    }
  | {
      readonly arguments: {
        readonly kind: 'page';
        readonly target: string;
        readonly graph?: string;
      };
      readonly command: 'explain';
      readonly form: 'target';
      readonly options?: {
        readonly optimistic?: false;
        readonly layouts?: boolean;
        readonly artifact?: string;
        readonly format?: 'human' | 'json' | 'github';
      };
    }
  | {
      readonly arguments: {
        readonly kind: 'context';
        readonly target: string;
        readonly graph?: string;
      };
      readonly command: 'explain';
      readonly form: 'target';
      readonly options?: {
        readonly optimistic?: false;
        readonly layouts?: false;
        readonly artifact?: string;
        readonly format?: 'human' | 'json' | 'github';
      };
    }
  | {
      readonly arguments: {
        readonly kind: 'task';
        readonly target: string;
        readonly graph?: string;
      };
      readonly command: 'explain';
      readonly form: 'target';
      readonly options?: {
        readonly optimistic?: false;
        readonly layouts?: false;
        readonly artifact?: string;
        readonly format?: 'human' | 'json' | 'github';
      };
    }
  | {
      readonly arguments: {
        readonly graph?: string;
      };
      readonly command: 'explain';
      readonly form: 'document';
      readonly options?: {
        readonly artifact?: string;
        readonly format?: 'human' | 'json' | 'github';
      };
    }
  | {
      readonly arguments: {
        readonly graph?: string;
      };
      readonly command: 'explain';
      readonly form: 'sources-sinks';
      readonly options?: {
        readonly artifact?: string;
        readonly format?: 'human' | 'json' | 'github';
      };
    }
  | {
      readonly arguments: {
        readonly graph?: string;
      };
      readonly command: 'explain';
      readonly form: 'tasks';
      readonly options?: {
        readonly artifact?: string;
        readonly format?: 'human' | 'json' | 'github';
      };
    }
  | {
      readonly arguments: {
        readonly graph?: string;
      };
      readonly command: 'explain';
      readonly form: 'agent';
      readonly options?: {
        readonly artifact?: string;
        readonly format?: 'human' | 'json' | 'github';
      };
    }
  | {
      readonly arguments: {
        readonly graph?: string;
      };
      readonly command: 'explain';
      readonly form: 'grants';
      readonly options?: {
        readonly artifact?: string;
        readonly format?: 'human' | 'json' | 'github';
      };
    }
  | {
      readonly arguments: {
        readonly graph?: string;
      };
      readonly command: 'explain';
      readonly form: 'endpoints';
      readonly options?: {
        readonly artifact?: string;
        readonly format?: 'human' | 'json' | 'github';
      };
    }
  | {
      readonly arguments: {
        readonly graph?: string;
      };
      readonly command: 'explain';
      readonly form: 'revealed';
      readonly options?: {
        readonly artifact?: string;
        readonly format?: 'human' | 'json' | 'github';
      };
    }
  | {
      readonly arguments: {
        readonly graph?: string;
      };
      readonly command: 'explain';
      readonly form: 'trust';
      readonly options?: {
        readonly artifact?: string;
        readonly format?: 'human' | 'json' | 'github';
      };
    }
  | {
      readonly arguments: {
        readonly graph?: string;
      };
      readonly command: 'explain';
      readonly form: 'capabilities';
      readonly options?: {
        readonly artifact?: string;
        readonly format?: 'human' | 'json' | 'github';
      };
    }
  | {
      readonly arguments: {
        readonly graph?: string;
      };
      readonly command: 'explain';
      readonly form: 'cookies';
      readonly options?: {
        readonly artifact?: string;
        readonly format?: 'human' | 'json' | 'github';
      };
    }
  | {
      readonly arguments: {
        readonly graph?: string;
      };
      readonly command: 'explain';
      readonly form: 'authorization';
      readonly options?: {
        readonly artifact?: string;
        readonly format?: 'human' | 'json' | 'github';
      };
    }
  | {
      readonly arguments: {
        readonly graph?: string;
      };
      readonly command: 'explain';
      readonly form: 'access';
      readonly options?: {
        readonly failOnFindings?: boolean;
        readonly artifact?: string;
        readonly format?: 'human' | 'json' | 'github';
      };
    }
  | {
      readonly arguments: {
        readonly graph?: string;
      };
      readonly command: 'explain';
      readonly form: 'unguarded';
      readonly options?: {
        readonly failOnFindings?: boolean;
        readonly artifact?: string;
        readonly format?: 'human' | 'json' | 'github';
      };
    }
  | {
      readonly arguments: {
        readonly graph?: string;
      };
      readonly command: 'explain';
      readonly form: 'unscoped';
      readonly options?: {
        readonly failOnFindings?: boolean;
        readonly artifact?: string;
        readonly format?: 'human' | 'json' | 'github';
      };
    }
  | {
      readonly arguments: { readonly [key: PropertyKey]: never };
      readonly command: 'explain';
      readonly form: 'auth-lifecycle';
      readonly options?: {
        readonly format?: 'human' | 'json' | 'github';
      };
    }
  | {
      readonly arguments: { readonly [key: PropertyKey]: never };
      readonly command: 'explain';
      readonly form: 'model-boundaries';
      readonly options?: {
        readonly format?: 'human' | 'json' | 'github';
      };
    }
  | {
      readonly arguments: {
        readonly url: string;
      };
      readonly command: 'explain';
      readonly form: 'attest';
      readonly options: {
        readonly artifact: string;
        readonly trustAnchor: string;
        readonly escapeReviews?: string;
        readonly escapeCensusReviews?: string;
        readonly format?: 'human' | 'json' | 'github';
      };
    }
  | {
      readonly arguments: {
        readonly appModule: string;
      };
      readonly command: 'export';
      readonly form: 'export';
      readonly options?: {
        readonly vite?: boolean;
        readonly root?: string;
        readonly out?: string;
        readonly origin?: string;
        readonly assetBase?: string;
        readonly skipNonExportable?: boolean;
      } & (
        | {
            readonly manifest?: never;
            readonly dist?: never;
          }
        | {
            readonly manifest: string;
            readonly dist: string;
          }
      );
    }
  | {
      readonly arguments: {
        readonly sources?: readonly string[];
      };
      readonly command: 'fix';
      readonly form: 'format';
      readonly options?: {
        readonly check?: boolean;
      };
    }
  | {
      readonly arguments: {
        readonly source: string;
      };
      readonly command: 'fix';
      readonly form: 'source';
      readonly options?: {
        readonly check?: boolean;
      };
    }
  | {
      readonly arguments: {
        readonly sources?: readonly string[];
      };
      readonly command: 'fix';
      readonly form: 'api-v1-check';
      readonly options: {
        readonly check: true;
      };
    }
  | {
      readonly arguments: {
        readonly sources?: readonly string[];
      };
      readonly command: 'fix';
      readonly form: 'api-v1-write';
      readonly options: {
        readonly write: true;
      };
    }
  | {
      readonly arguments: { readonly [key: PropertyKey]: never };
      readonly command: 'fix';
      readonly form: 'cost-report';
      readonly options: {
        readonly costReport: true;
      };
    }
  | {
      readonly arguments: {
        readonly advisory: string;
      };
      readonly command: 'incident';
      readonly form: 'scope';
      readonly options: {
        readonly events: string;
      };
    }
  | {
      readonly arguments: {
        readonly files?: readonly string[];
      };
      readonly command: 'test';
      readonly form: 'test';
      readonly options?: {
        readonly coverage?: boolean;
        readonly update?: boolean;
        readonly passWithNoTests?: boolean;
        readonly reporter?: 'default' | 'basic' | 'dot' | 'json' | 'junit' | 'verbose';
        readonly testNamePattern?: string;
      };
    }
  | {
      readonly arguments: { readonly [key: PropertyKey]: never };
      readonly command: 'update-docs';
      readonly form: 'update-docs';
      readonly options?: { readonly [key: PropertyKey]: never };
    };
```