Skip to content

kyvvu command reference

Configuration file

kyvvu auth writes the API URL and key to ~/.kyvvu/config.toml, with file mode 0600, and the kyvvu command line reads them from there. Precedence for the command line and kyvvu serve: flags, then environment variables (including .env), then config.toml. kyvvu doctor reports which .env it found. The engine itself never reads this file; its settings are on the Engine settings page.

Integrations and plugins

kyvvu integrations lists the host integrations (Claude Code), whether each is installed, and the command that installs one that is not, followed by the project libraries and the command that adds each to a project.

A host integration is a plugin: an installed distribution that adds a kyvvu <name> command. Claude Code support is the claude-code extra of kyvvu-cli, which installs the plugin that adds kyvvu claude. A plugin declares an entry point in the kyvvu.cli_plugins group, naming a Python module:

[project.entry-points."kyvvu.cli_plugins"]
myplugin = "my_package.cli"

The module's app must be a Typer application; it is added as kyvvu <entry point name>. The module may also define status() -> str, its line in kyvvu integrations, and doctor() -> kyvvu_cli.doctor.Check, its check in kyvvu doctor (including --json). A plugin that fails to import, or whose status() or doctor() raises, prints one warning and leaves every other command and check working.

kyvvu

The kyvvu command: try policies offline, scaffold and diagnose agents, serve the engine, and manage platform agents and manifests.

Argument or option Type Required Default Environment Meaning
--version, -v boolean False False Print version and exit.
--install-completion boolean False None Install completion for the current shell.
--show-completion boolean False None Show completion for the current shell, to copy it or customize the installation.

kyvvu acs

Run the Kyvvu Guardian for the OWASP Agent Control Standard (ACS).

kyvvu acs serve

Start the ACS Guardian over HTTP for one agent.

Policy sources mirror kyvvu serve: --policy-file (repeatable), --baseline, or the platform via --api-key alone (--api-url and --agent-key default and are optional; the Guardian self-registers the agent). With no source named the command exits with the three-option message.

Argument or option Type Required Default Environment Meaning
--host str False '127.0.0.1' Bind address (loopback by default).
--port int False 8787 Bind port for POST /acs.
--policy-file str False None Manifest YAML to enforce. Repeatable; each value may be comma-separated.
--baseline boolean False False Enforce the ACS Guardian policies bundled in kyvvu-acs.
--api-url str False None KV_API_URL Kyvvu platform API URL (platform-policy mode). Optional; defaults to https://platform.kyvvu.com.
--api-key str False None KV_API_KEY Bearer API key (platform-policy mode). On its own it selects the platform source. Prefer KV_API_KEY over the flag.
--agent-key str False None KV_AGENT_KEY Agent key to register under and whose policies to fetch. Optional; defaults to a stable acs-- key.
--template path False None A template overlay YAML (deep-merged, overlay rules first).
--on-decision-failure str False 'deny' What to answer when a decision cannot be produced: deny (fail closed) or proceed (fail open).
--allow-unsigned boolean False False Accept unsigned envelopes (the reference shims emit no signature).
--ask boolean False False Resolve an approval gate as an ask; off by default, so a gate-only block is denied.

kyvvu assign-manifest

Assign a manifest to an agent.

Argument or option Type Required Default Environment Meaning
--agent-id str True None The agent: its agent_... id or its agent key
--repo-id int True None Repository ID
--manifest str True None Manifest file path

kyvvu auth

Log in via the device-code flow.

Argument or option Type Required Default Environment Meaning
--api-url str False None Kyvvu API URL
--device-label str False None Label for this device (defaults to hostname)

kyvvu claude

Kyvvu compliance integration for Claude Code.

kyvvu claude hooks

Manage Claude Code hooks

kyvvu claude hooks install

Install Claude Code hooks for compliance monitoring.

Argument or option Type Required Default Environment Meaning
--project boolean False False Write to .claude/settings.json in cwd

kyvvu claude hooks remove

Remove Kyvvu's hooks from Claude Code settings.

Argument or option Type Required Default Environment Meaning
--project boolean False False Remove from .claude/settings.json in cwd

kyvvu claude policies

Display cached policies as a table.

kyvvu claude refresh

Force policy refresh from the API.

kyvvu claude report

Replay past Claude Code sessions and show what the manifest would flag.

Reads the transcripts Claude Code keeps under ~/.claude/projects and, for each, replays every tool call through the same mapper and engine the hooks use. It fetches nothing, uploads nothing and changes nothing: the replayed sessions never leave the machine.

Argument or option Type Required Default Environment Meaning
--since str False '30d' Replay sessions modified within this window (e.g. 30d, 7d, 12h).
--project path False None Limit to one project directory (default: all).
--manifest path False None Replay against this manifest file instead of the configured source.
--json boolean False False Emit the report as JSON.

kyvvu claude set

Set one Claude integration option in the saved configuration.

Argument or option Type Required Default Environment Meaning
name str True None
value str True None

kyvvu claude setup

One-step setup: paste one API key, or --local for no account.

With no flags and no KV_API_KEY, the only prompt is a hidden API-key paste; every other value comes from its flag, an environment variable or the default. --monitor turns enforcement into logging; --local configures the integration with no account at all.

Argument or option Type Required Default Environment Meaning
--local boolean False False Configure without an account, enforcing the bundled Claude Code Safety manifest offline. No registration, fetch or upload.
--monitor boolean False False Monitor only: evaluate and log violations without blocking (sets enforce=false).
--manifest path False None With --local, enforce this manifest file instead of the bundled Claude Code Safety manifest.
--fail-mode str False None Allow failures (open) or deny PreToolUse on failure (closed).
--api-url str False None KV_API_URL Kyvvu API URL. Default: kyvvu auth login, else https://platform.kyvvu.com.
--api-key str False None KV_API_KEY Kyvvu agent API key (Workspace → API Keys). Default: a single hidden paste prompt. Prefer the KV_API_KEY variable: an option is visible in the process list and shell history.
--owner str False None Email of the workspace member accountable for this agent (EU AI Act owner). Default: the API key owner's email, filled in by the platform.
--agent-key str False None Agent key to register under. Default: claude-code--.
--environment str False None development, qa, staging or production. Default: KV_ENVIRONMENT, else production.

kyvvu claude status

Show current kyvvu claude status.

kyvvu docs

Print versioned documentation and agent indexes for installed packages.

kyvvu doctor

Diagnose this machine: versions, credentials, and what is actually enforced.

Argument or option Type Required Default Environment Meaning
--api-url str False None Kyvvu API URL every check uses (overrides KV_API_URL)
--agent-key str False None Agent to diagnose. Defaults to KV_AGENT_KEY; without one the policy and trace-sink checks cannot resolve an API policy set.
--json boolean False False Emit JSON instead of a report.
--python path False None Project Python interpreter or virtual environment.

kyvvu explain

Explain an installed rule or exception without contacting the platform.

Argument or option Type Required Default Environment Meaning
name str True None A rule name or public exception class.

kyvvu init

Create a new Kyvvu agent project.

Argument or option Type Required Default Environment Meaning
project_name str False None Project directory name

kyvvu integrations

List host integrations and project libraries with install commands.

kyvvu list-agents

List registered agents.

Argument or option Type Required Default Environment Meaning
--environment str False None Filter by environment (development, qa, staging, production)
--include-inactive boolean False False Include inactive (deactivated) agents

kyvvu list-assignments

List manifest assignments.

Argument or option Type Required Default Environment Meaning
--agent-id str False None Filter by agent: its agent_... id or its agent key

kyvvu list-manifests

List available manifests from connected repositories.

Argument or option Type Required Default Environment Meaning
--repo-id int False None Filter by repo ID

kyvvu list-policies

List policies.

Argument or option Type Required Default Environment Meaning
--agent-id str False None Filter by agent: its agent_... id or its agent key
--enforcement-point str False None Filter by enforcement point (agent_registration, step_execution)
--enabled, --disabled boolean False None Filter by enabled state

kyvvu logout

Log out (clear auth session, keep API key).

kyvvu schema

Inspect installed editor schemas and validate with native contracts.

kyvvu schema manifest

Print the manifest editor schema, or validate a file using the engine.

Argument or option Type Required Default Environment Meaning
--validate path False None Validate a manifest YAML with the parser and engine.

kyvvu serve

Start one local policy sidecar per agent; trust local callers.

Argument or option Type Required Default Environment Meaning
--host str False '127.0.0.1' Bind address
--port int False 8080 Bind port
--uds path False None Private Unix-domain socket path
--token-file path False None File holding the per-install token the private socket requires (owner-only, mode 0600). Required with --uds.
--profile path False None Agent profile YAML
--api-url str False None Kyvvu platform API URL
--api-key str False None Bearer API key
--agent-key str False None Agent key for policy fetch
--policy-file str False None Manifest YAML to enforce locally (repeatable). No credentials needed.
--baseline boolean False False Enforce the bundled frozen baseline set. No credentials needed.
--allow-ungoverned boolean False False Start even when no policies are in effect.
--idle-exit float False 0.0 Stop after this many seconds without a request (0 = never).
--policy-cache-path str False None On-disk policy cache to load from and refresh into (the per-session serve shares the hook's cache).

kyvvu template

Inspect behaviour templates supplied by installed packages.

kyvvu template show

Print an installed template to stdout, to copy and edit.

Works from any install, including a wheel: After installing kyvvu-langchain, for example, use kyvvu template show langchain > my.yaml. A custom template replaces the supplied template, so start from a copy that covers every task boundary.

Argument or option Type Required Default Environment Meaning
name str True None Template name from the Python client or an installed integration package.
--python path False None Project Python interpreter or virtual environment.

kyvvu try

Enforce policies offline — no account, no API key, no network.

Argument or option Type Required Default Environment Meaning
--manifest, -m str False None Manifest YAML to enforce (repeatable). Default: the bundled frozen baseline.
--steps str False None YAML file describing your own behaviour path.
--json boolean False False Emit JSON instead of a report.
--record-trial boolean False False Opt in to a local trial marker in ~/.kyvvu. Off by default; sent nowhere.
--forget-trial boolean False False Delete the local trial marker and exit.

kyvvu unassign-manifest

Remove a manifest assignment.

Argument or option Type Required Default Environment Meaning
--assignment-id int True None Assignment ID (the ID column of list-assignments)

kyvvu whoami

Show current user info, account status, and endpoint configuration.