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