Skip to content

Use secrets without seeing them

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.

Updated

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:

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

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.

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:

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

klav agent inject --reason "Write the test config" -r klav://Personal/General/Stripe/api_key -o stripe.key --ttl 1m
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:

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.

Type to search…

↑↓ navigate↵ selectEsc close