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 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 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¶
Interactive setup: configure API connection and register agent.
| Argument or option | Type | Required | Default | Environment | Meaning |
|---|---|---|---|---|---|
--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: 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 | |
--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. |
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.