---
title: "Use secrets without seeing them"
description: "Put API keys into a command's environment or a file, and type logins into a browser page, without Klav returning the value to an agent: klav.toml, klav run, klav agent run, inject and fill."
image: "https://docs.klav.dev/og.png"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.klav.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Use secrets without seeing them

This page explains how a secret gets to where it is used without passing through the agent: into a command's environment, into a file, or into a browser page. The same tools work for you, with `klav run` and `klav inject`, and for an agent, with `klav agent run`, `inject` and `fill` or their `klav mcp` tools.

## References and `klav.toml`

Every field has a reference such as `klav://Personal/General/Stripe/api_key`. A `klav.toml` at the root of a repository lists the references a project needs. It holds no secrets, so you can commit it:

```toml
project = "Work/acme-api"          # optional: allows short references

[env]
STRIPE_KEY   = "klav://Work/acme-api/Stripe/api_key"
DATABASE_URL = "Postgres/url"      # short for klav://Work/acme-api/Postgres/url

[files]
"secrets/AuthKey.p8" = "klav://Work/app-ios/APNs/key"
```

- `klav run` and `klav inject` use the nearest `klav.toml`, from the current folder up to the root of the git repository or your home folder. `--config` chooses another.
- `[files]` paths are relative to the `klav.toml` and can't leave its folder.
- An unknown key in the file is an error.
- The first time `klav run` uses a `klav.toml`, and every time it changes, it shows what it asks for and asks you to confirm. A repository you just cloned can't put your secrets into a command it also controls.
- An agent that starts in that folder sees only that project.

## For you: `klav run` and `klav inject`

```sh
klav run -- npm run dev
klav run -e EXTRA=klav://Personal/General/Token/value -- ./script.sh
```

`klav run` resolves every reference before it starts anything, writes the `[files]` with mode 0600, runs the command with the secrets in its environment only (never in its arguments), and deletes the files when the command ends. It exits with the command's code.

```sh
klav inject -i .env.tpl -o .env                     # a template: each {{ klav://… }} replaced
klav inject -r klav://Work/app-ios/APNs/key -o ./AuthKey.p8 --ttl 10m
klav inject -r APNs/key -o ./AuthKey.p8 --fifo      # a named pipe, read once, never on disk
```

A file `klav inject` writes is plain text on disk while it exists. Prefer `klav run`, or `--fifo` when the tool can read from a pipe.

## For agents

The agent's commands work the same way, with the agent's identity and a required `--reason`. They all accept `--wait`, `--approval` and `--agent`, and use `klav.toml` like `klav run`.

### `klav agent run`

Runs a command with secrets in its environment (permission `inject`). The output comes back after the command ends, with each value replaced:

```sh
klav agent run --reason "Run the billing tests against Stripe's test mode" \
  -e STRIPE_KEY=klav://Personal/General/Stripe/api_key -- sh -c 'echo "key is $STRIPE_KEY"'
```

```text
key is [redacted by klav]
warning: secret values were removed from the output in 1 place(s)
```

The redaction also catches the value in base64, hex, URL encoding and JSON escaping, and pieces of it 12 characters or longer. It is a safety net for mistakes, not a sealed channel: the command has the value, and a command written to get it out can. `--timeout` stops the command (10 minutes by default). The MCP tool is `run_with_secrets`.

### `klav agent inject`

Writes a secret, a template or an attachment (a `.p8`, a certificate) into a **new** file with mode 0600. It never writes to standard output, so Klav doesn't return the value to the agent. The file is in the agent's folder, though: an agent that reads it gets the value.

```sh
klav agent inject --reason "Write the test config" -r klav://Personal/General/Stripe/api_key -o stripe.key --ttl 1m
```

```text
Wrote stripe.key (mode 0600); removing it in 1m.
Removed stripe.key.
```

With `--ttl`, `klav` stays in the foreground and deletes the file when the time is up. The MCP tool is `inject_file`, which writes only inside its working folder and answers with the path, never the content. Neither writes a one-time code's secret: codes go through `get_totp`.

### `klav agent fill`

Types a login or a card into a browser page (permission `fill`). Klav never returns the values to the agent:

```sh
klav agent fill klav://Personal/General/GitHub --reason "Sign in to GitHub to open the release PR" --extension --submit
```

- `--extension` types into the active tab of your browser, through Klav's extension, and the page shows the agent's name and reason. `--cdp http://127.0.0.1:9222` types into a Chrome or Chromium tab the agent controls. Klav connects only to browsers on the same computer. An agent that controls that browser can read a field after Klav fills it.
- Before it types, Klav checks that the page is `https` (or `http` on `127.0.0.1`) and that its host is one of the item's sites or a subdomain. If not, it refuses: that is the protection against phishing.
- Right before each field, it checks the field's type (the password goes only into a password input), that it has the focus, and that the tab is still on the site.
- It prints the names of the fields it filled, never the values. `--submit` also submits the form, only one whose action is on the page's own origin, and says where the page went.

The MCP tools are `fill_login` and `fill_card`, with `target: "extension"` for your browser.

## Next

[The activity log](https://docs.klav.dev/agents/activity-log/).

Source: https://docs.klav.dev/agents/use-secrets-without-seeing-them/index.mdx
