CLI Reference

Complete reference for kz commands, HTTP API, and environment variables

kz server start

Start the PDP server (HTTP or MCP mode).

kz server start --bundle <path> [--listen <addr>] [--mcp] [--proxy]

Flag	Description	Default
`-b, --bundle <PATH>`	Path to the bundle YAML file	Required
`-l, --listen <ADDR>`	Listen address	`0.0.0.0:8080`
`--mcp`	Run as MCP server over stdio instead of HTTP	`false`
`--proxy`	Enable the credential-swapping proxy	`false`

kz server check

Validate a bundle file without starting a server.

kz server check --bundle <path>

Flag	Description	Default
`-b, --bundle <PATH>`	Path to the bundle YAML file	Required

Validates:

YAML syntax and schema
CEL rule compilation
All resource resolvers reference existing backends

kz run

Run a command with secrets resolved and injected.

kz run [OPTIONS] -- <COMMAND>...

Flag	Description	Default
`--only <KEYS>`	Resolve only the listed secret keys	All secrets
`--clean-env`	Start with a clean environment (only injected secrets)	`false`
`--keep-env <KEYS>`	When using `--clean-env`, also keep these host env vars	None
`--blind`	Mask secrets with tokens; run MITM proxy to swap at the network boundary	`false`
`--no-force-proxy`	In blind mode, don't force-set proxy env vars	`false`

kz init

Create a starter .keyzero.toml in the current directory.

kz init

kz add

Interactively add a secret mapping to .keyzero.toml.

kz add

kz put

Write secret values to a provider.

kz put --missing

Flag	Description
`--missing`	Only prompt for secrets that don't have a value yet

kz export

Print export KEY='VALUE' lines for shell eval.

kz export

kz status

Show resolution status for each secret in the config.

kz status

kz validate

Check the config file for errors.

kz validate

kz hook

Print a shell hook for auto-loading secrets when entering a project directory.

kz hook --shell <zsh|bash|fish>

HTTP API

GET /healthz

Health check endpoint. No authentication required.

Response (200):

{
  "status": "ok",
  "bundle_loaded": true,
  "bundle_version": "1"
}

POST /v1/resolve

Resolve secrets for a resource through the full pipeline.

Headers:

Header	Value
`Authorization`	`Bearer <jwt>`
`Content-Type`	`application/json`

Request body (single):

{
  "ref": "secret/data/prod/pg/conn"
}

Request body (batch):

{
  "refs": ["secret/data/prod/pg/conn", "secret/data/ai/key"],
  "context": {
    "action": "startup"
  }
}

Success response -- direct mode (200):

{
  "results": {
    "secret/data/prod/pg/conn": {
      "allowed": true,
      "policy": "allow-prod",
      "mode": "direct",
      "value": "postgres://..."
    }
  }
}

Success response -- short_lived mode (200):

{
  "results": {
    "secret/data/ai/key": {
      "allowed": true,
      "policy": "allow-ai",
      "mode": "short_lived",
      "token": "eyJ...",
      "proxy": "https://...",
      "ttl": 300
    }
  }
}

Denied response (200):

{
  "results": {
    "secret/data/prod/pg/conn": {
      "allowed": false,
      "policy": "default-deny",
      "reason": "..."
    }
  }
}

Error responses:

Status	Error	Description
401	`invalid_token`	Missing, malformed, or invalid JWT
400	`invalid_ref`	Path traversal or malformed ref
404	`unknown_ref`	Ref not found in bundle
500	`internal_error`	Backend or internal failure

Environment Variables

kz server start

Variable	Used By	Description
`RUST_LOG`	All	Log level filter (e.g., `kz=debug`)
`KEYZERO_SIGNING_KEY_PATH`	`server start`	Path to RSA private key PEM for signing short-lived JWTs
`KEYZERO_PUBLIC_KEY_PATH`	`server start --proxy`	Path to RSA public key PEM for verifying short-lived JWTs
`KEYZERO_PROXY_URL`	`server start`	Proxy URL returned in short-lived mode responses
`VAULT_TOKEN`	Vault backend	HashiCorp Vault authentication token
`GOOGLE_ACCESS_TOKEN`	GCP backend	Google Cloud access token

kz

Variable	Used By	Description
`KEYZERO_ENV`	`kz run`	Active environment section (e.g., `production`, `staging`)
`VAULT_TOKEN`	Vault provider	HashiCorp Vault authentication token
`GOOGLE_ACCESS_TOKEN`	GCP provider	Google Cloud access token

Set by kz on subprocess

Variable	Description
`HTTP_PROXY`, `http_proxy`	Local MITM proxy address (blind mode)
`HTTPS_PROXY`, `https_proxy`	Local MITM proxy address (blind mode)
`SSL_CERT_FILE`	Ephemeral CA certificate path
`NODE_EXTRA_CA_CERTS`	Ephemeral CA certificate path (Node.js)
`REQUESTS_CA_BUNDLE`	Ephemeral CA certificate path (Python)