@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:

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.

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>`

Examples

kovo add button

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

kovo audit#

Run security and access audits over an app graph.

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

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

Examples

kovo audit

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

kovo doctor#

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

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

Flag	Description
`--fix`	Apply only framework-classified safe repairs.
`--format <human	json

Examples

kovo doctor

kovo doctor --format json

kovo doctor --fix

kovo build#

Prove and build an authored Kovo app for deployment.

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

Examples

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

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

kovo check#

Run consistency, security, environment, and advisory verification.

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
`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>`
`--attestation <url	file>`
`--state <file>`	Override the local advisory epoch/equivocation state file. Default: .kovo/advisory-state.json.
`--severity-floor <low	moderate
`--format <human	json
`--artifact <graph.json>`	Inspect the explicitly named completed build graph.

Examples

kovo check

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

kovo check source --watch --format json

kovo check lifecycle

kovo check coverage graph.json

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

kovo check env deployment.json

kovo check advisories .kovo/graph.json

kovo compile#

Emit compiler-owned artifacts without importing compiler internals.

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

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

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

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

kovo db#

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

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
`--schema <module>`	Schema module path. Default: src/schema.ts.
`--migrations <dir>`	Directory of reviewed SQL migrations. Default: migrations.
`--driver <pglite	pg
`--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

kovo db provision --schema src/schema.ts

kovo db check --driver pglite

kovo dev#

Start the bootstrap-first Kovo development server.

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

kovo dev ./src/app.tsx

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

kovo docs#

Search the exact version-matched local Kovo documentation snapshot.

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

Flag	Description
`--limit <count>`	Maximum number of authenticated local results. Default: 5.
`--format <human	json>`

Examples

kovo docs quickstart

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

kovo explain#

Render stable proof facts for a subject or security review.

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
`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

Examples

kovo explain component Cart graph.json

kovo explain capabilities

kovo explain access --fail-on-findings

kovo export#

Export a Kovo app as static hosting output.

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

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

kovo fix#

Apply only compiler-proven safe TSX/JSX rewrites.

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

kovo fix src/components/cart.tsx

kovo fix format src

kovo fix api-v1 --check

kovo fix --cost-report

kovo incident#

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

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

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

kovo mcp#

Serve the finite Kovo MCP protocol over stdio.

usage: kovo mcp

Examples

kovo mcp

kovo test#

Run app tests with Kovo runtime ordering established first.

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

kovo test

kovo test src/app.test.ts

kovo test --coverage

kovo update-docs#

Refresh version-matched agent-readable Kovo documentation.

usage: kovo update-docs

Examples

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

Values#

`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

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

`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

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

`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

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

`KOVO_DIAGNOSTIC_VERSION`#

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

Signature

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

Supporting types#

`KovoCliDiagnosticCode`#

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

Signature

type KovoCliDiagnosticCode = keyof typeof CLI_DIAGNOSTIC_DEFINITIONS;

`KovoDiagnosticCategory`#

Stable categories used to classify CLI process behavior.

Signature

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

`KovoDiagnosticCommandResult`#

Existing command result carried intact beside the shared diagnostics.

Signature

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

`KovoDiagnosticEnvelope`#

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

Signature

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`#

Presentation adapters supported by {@link formatKovoDiagnostics}.

Signature

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

`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

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`#

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

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

`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

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

`KovoAccessExplainOptions`#

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

Signature

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

`KovoAgentExplainOptions`#

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

Signature

interface KovoAgentExplainOptions {
  view: 'agent';
}

`KovoAuthLifecycleExplainOptions`#

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

Signature

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

`KovoAuthorizationExplainOptions`#

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

Signature

interface KovoAuthorizationExplainOptions {
  view: 'authorization';
}

`KovoCheckFamily`#

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

Signature

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

`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

type KovoCheckInput = unknown;

`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

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

`KovoCommandExitCode`#

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

Signature

type KovoCommandExitCode = 0 | 1 | 2;

`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

interface KovoDocumentExplainOptions {
  view: 'document';
}

`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

interface KovoEndpointExplainOptions {
  view: 'endpoints';
}

`KovoExplainInput`#

Opaque graph input accepted by kovoExplain.

Signature

type KovoExplainInput = unknown;

`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

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`#

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

Signature

interface KovoGrantExplainOptions {
  view: 'grants';
}

`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

interface KovoRevealedExplainOptions {
  view: 'revealed';
}

`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

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

`KovoTasksExplainOptions`#

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

Signature

interface KovoTasksExplainOptions {
  view: 'tasks';
}

`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

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

`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

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

`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

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

`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

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

@kovojs/cli

Commands#

kovo add#

kovo audit#

kovo doctor#

kovo build#

kovo check#

kovo compile#

kovo db#

kovo dev#

kovo docs#

kovo explain#

kovo export#

kovo fix#

kovo incident#

kovo mcp#

kovo test#

kovo update-docs#

Programmatic API#

@kovojs/cli#

Values#

kovoCheck#

kovoExplain#

runKovoCommand#

KOVO_DIAGNOSTIC_VERSION#

Supporting types#

KovoCliDiagnosticCode#

KovoDiagnosticCategory#

KovoDiagnosticCommandResult#

KovoDiagnosticEnvelope#

KovoDiagnosticFormat#

KovoDiagnosticRecord#

KovoDiagnosticSourceAnchor#

ExplainKind#

KovoAccessExplainOptions#

KovoAgentExplainOptions#

KovoAuthLifecycleExplainOptions#

KovoAuthorizationExplainOptions#

KovoCheckFamily#

KovoCheckInput#

KovoCheckResult#

KovoCommandExitCode#

KovoDocumentExplainOptions#

KovoEndpointExplainOptions#

KovoExplainInput#

KovoExplainOptions#

KovoGrantExplainOptions#

KovoRevealedExplainOptions#

KovoSourcesSinksExplainOptions#

KovoTasksExplainOptions#

KovoTargetExplainOptions#

KovoUnguardedExplainOptions#

KovoUnscopedExplainOptions#

KovoSemanticCommandRequest#

`@kovojs/cli`#

`kovoCheck`#

`kovoExplain`#

`runKovoCommand`#

`KOVO_DIAGNOSTIC_VERSION`#

`KovoCliDiagnosticCode`#

`KovoDiagnosticCategory`#

`KovoDiagnosticCommandResult`#

`KovoDiagnosticEnvelope`#

`KovoDiagnosticFormat`#

`KovoDiagnosticRecord`#

`KovoDiagnosticSourceAnchor`#

`ExplainKind`#

`KovoAccessExplainOptions`#

`KovoAgentExplainOptions`#

`KovoAuthLifecycleExplainOptions`#

`KovoAuthorizationExplainOptions`#

`KovoCheckFamily`#

`KovoCheckInput`#

`KovoCheckResult`#

`KovoCommandExitCode`#

`KovoDocumentExplainOptions`#

`KovoEndpointExplainOptions`#

`KovoExplainInput`#

`KovoExplainOptions`#

`KovoGrantExplainOptions`#

`KovoRevealedExplainOptions`#

`KovoSourcesSinksExplainOptions`#

`KovoTasksExplainOptions`#

`KovoTargetExplainOptions`#

`KovoUnguardedExplainOptions`#

`KovoUnscopedExplainOptions`#

`KovoSemanticCommandRequest`#