# kv-secrets — Agent Guide

> This file is for AI coding agents (Claude Code, Cursor, etc.).
> It tells you how to use API keys in this project.

## API calls

Use the `kv_api` MCP tool for all API calls. Credentials are injected automatically.
The API key stays in the daemon — it never enters your process.

```
kv_api(provider="openai", path="/v1/chat/completions", method="POST", body={
  "model": "gpt-4",
  "messages": [{"role": "user", "content": "Hello"}]
})

kv_api(provider="anthropic", path="/v1/messages", method="POST", body={
  "model": "claude-sonnet-4-20250514",
  "max_tokens": 1024,
  "messages": [{"role": "user", "content": "Hello"}]
})

kv_api(provider="google", path="/v1beta/models/gemini-pro:generateContent", method="POST", body={
  "contents": [{"parts": [{"text": "Hello"}]}]
})

kv_api(provider="github", path="/user/repos", method="GET")
```

Check available providers: `kv_list()` shows stored secret names.
Custom providers may be configured — use `kv_status()` to see what's available.

## Running apps

Use `kv_run` for applications that need API keys as environment variables
(databases, cloud SDKs, legacy apps). The daemon must be running.

```
kv_run(argv=["python3", "app.py"])
kv_run(argv=["npm", "start"])
kv_run(argv=["pytest", "tests/"])
```

Output is redacted — secret values are replaced with [REDACTED] before
you see them. Network access is controlled by the user's security policy.

## Checking what's available

```
kv_status()       # Vault status
kv_list()         # Secret names (values are hidden)
kv_envs()         # Available environments
```

Use a specific environment: `kv_api(..., env="work")` or `kv_run(..., env="staging")`.

## If the vault is locked

Tell the user: "Run `kv unlock` in a separate terminal."

Do not attempt to unlock it — this requires the user's passphrase.

## Important

- API keys are managed by the user. Do not ask for them in chat.
- Use `kv_api` for HTTP calls — the key never leaves the daemon.
- Use `kv_run` for apps that need env vars (databases, SDKs).
- Do not run `kv init`, `kv setup-2fa`, or `kv upgrade-security` — these are user actions.
- Do not attempt to read `.secrets/key` or `.secrets/*.enc` files.
