Using secrets from code

Status: in development; not yet released. Every command and package on this page is the planned interface. None of it is available today, and the package names are proposed. Background: Console secrets service.

Your code never calls the console. It reads secrets from a process that tm secrets exec starts. There are three ways to do that.

Each key resolves in the project's scope first, then the owner's scope.

Environment variables

tm secrets exec looks up the project's keys, sets each one as an environment variable, and starts your command.

# Planned interface — not available yet.
tm secrets exec -- python app.py
tm secrets exec -- node server.js
tm secrets exec -- cargo run

Your code reads the variable the normal way.

Python:

# Planned interface: run with `tm secrets exec -- python app.py`.
import os

api_key = os.environ["STRIPE_KEY"]

Node:

// Planned interface: run with `tm secrets exec -- node server.js`.
const apiKey = process.env.STRIPE_KEY;
if (!apiKey) throw new Error('STRIPE_KEY is not set');

The values exist only in the environment of the started process and its children.

.env files with secret:// references

Keep your .env file. Replace each secret value with a secret:// reference to a key. A reference is a key name, not a value, so the file is safe to commit.

# .env — planned interface
STRIPE_KEY=secret://STRIPE_KEY
DATABASE_URL=secret://DATABASE_URL
LOG_LEVEL=info

Start your program with --dotenv:

# Planned interface — not available yet.
tm secrets exec --dotenv .env -- npm run dev

tm secrets exec reads the file, resolves each secret:// entry, and passes the plain entries through unchanged. Your program sees STRIPE_KEY, DATABASE_URL and LOG_LEVEL as ordinary environment variables. Your program does not need a dotenv library for this.

Language clients

A client library fetches one key while your program runs, instead of at start. Three are planned. All names are proposed.

A client works only inside a process that tm secrets exec started. The service checks a token, the key, and the process ancestry. A client call from any other process fails. The client API is not designed yet, so this page shows no client code.

Agents and your code

An agent may use every key in your scope unless you denied the key to agents. A denied key is never set in a process whose parent chain includes Claude Code. If an agent runs your tests and a key is missing, check whether that key is denied in the console. See Secrets security model for what the deny does and does not protect.