Guide

Using secr with AI Coding Agents

AI agents write better code when they understand your tooling. This guide shows you how to configure Claude Code, Cursor, GitHub Copilot, and Windsurf to work with secr — so your agent never creates .env files, never hardcodes secrets, and uses secr run by default.

The Goal

After following this guide, your AI agent will:

Reference secrets via process.env.KEY_NAME, never inline values
Use secr run in dev scripts and Dockerfiles
Never create, modify, or read .env files
Know how to add new secrets with secr set
Know how to import existing secrets from other platforms

Claude Code

Claude Code reads CLAUDE.md at the root of your project at the start of every session. Add this block:

CLAUDE.md

## Secrets Management

This project uses secr for secrets management. Follow these rules strictly:

### Rules
- NEVER hardcode secret values in source files. Always use `process.env.SECRET_NAME`.
- NEVER create, modify, or read .env files. There are no .env files in this project.
- NEVER log, print, or include secret values in comments, documentation, or error messages.
- NEVER commit files that contain secret values.

### How Secrets Work
- Secrets are stored encrypted in secr, organized by environment (development, staging, production).
- For local dev, run commands with: `secr run -- <command>`
- To add a new secret: `secr set KEY=value`
- To add multiple secrets: `secr set --from-env file.env`
- To import from another platform: `secr import --from <provider> --key <key> --service-id <id>`
- To list current secrets: `secr ls`

### Dev Scripts
All dev scripts should use secr run:
```json
{
  "dev": "secr run -- tsx watch src/server.ts",
  "test": "secr run --env staging -- vitest",
  "build": "secr run -- next build"
}
```

### When You Need a New Secret
1. Tell the user: "This feature needs a new secret: `SECRET_NAME`. Add it with `secr set SECRET_NAME=value`."
2. Reference it in code as `process.env.SECRET_NAME`.
3. Do NOT create a placeholder value or .env file.

Tip: Project-specific secrets

If your project has specific secret names, list them in CLAUDE.md so the agent knows what's available. For example: “Available secrets: DATABASE_URL, REDIS_URL, STRIPE_SECRET_KEY, RESEND_API_KEY”. Run secr ls to get the list.

Cursor

Cursor reads .cursorrules from your project root. Add these rules:

.cursorrules

# Secrets Management
This project uses secr for secrets. Do NOT use .env files.
- Access secrets via process.env.SECRET_NAME in code.
- Run local dev with: secr run -- <command>
- Add new secrets with: secr set KEY=value
- Never hardcode credentials, API keys, or tokens in source files.
- Never create .env, .env.local, or .env.production files.
- If a feature requires a new secret, reference process.env.NEW_KEY and
  tell the user to run: secr set NEW_KEY=value

Cursor + secr run

If you use Cursor's integrated terminal, prefix your dev command with secr run -- so the agent's terminal has access to secrets without files on disk.

GitHub Copilot

Copilot reads .github/copilot-instructions.md for repository-level guidance:

.github/copilot-instructions.md

# Secrets

This project uses secr for secrets management. There are no .env files.

- Always access secrets via process.env (e.g. process.env.DATABASE_URL).
- Never hardcode secret values in source code.
- Never create .env files.
- Dev server: secr run -- npm run dev
- Add a secret: secr set KEY=value

Copilot's instruction file support was added in 2024. If your team uses older versions, add the same rules as code comments in a top-level CONTRIBUTING.md.

Windsurf

Windsurf reads .windsurfrules from your project root:

.windsurfrules

# Secrets Management
This project uses secr for secrets. Do NOT use .env files.
- Access secrets via process.env.SECRET_NAME in code.
- Run local dev with: secr run -- <command>
- Add new secrets with: secr set KEY=value
- Never hardcode credentials, API keys, or tokens in source files.
- Never create .env, .env.local, or .env.production files.

Common Recipes

Copy-paste these into your agent conversation when you need them.

“Set up a new project with secr”

Terminal

# Initialize secr in your project
secr init

# Import existing .env file, then delete it
secr set --from-env .env
rm .env
echo ".env*" >> .gitignore

# Install pre-commit secret scanner
secr guard install

# Run your dev server through secr
secr run -- npm run dev

“Add a third-party service integration”

When the agent adds a new service (Stripe, OpenAI, Resend, etc.):

Prompt to your agent

Add the Stripe integration. The secret key is managed by secr.
Reference it as process.env.STRIPE_SECRET_KEY in the code.
I'll add the actual value with: secr set STRIPE_SECRET_KEY=sk_live_...

The agent writes the code referencing process.env.STRIPE_SECRET_KEY. You add the real value separately. The secret never enters the agent's context.

“Migrate from another platform”

Terminal

# Pull env vars from Heroku into secr
secr import --from heroku --key $HEROKU_API_KEY --service-id my-app

# Pull from Vercel
secr import --from vercel --key $VERCEL_TOKEN --service-id prj-abc123

# Pull from Render
secr import --from render --key $RENDER_API_KEY --service-id srv-abc123

“Set up CI/CD”

.github/workflows/test.yml

- name: Pull secrets and run tests
  uses: secr/action@v1
  with:
    org: my-org
    project: my-project
    environment: staging
    token: ${{ secrets.SECR_TOKEN }}
- run: npm test

“Write a Dockerfile”

Dockerfile

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --production
COPY . .

# Don't bake secrets into the image.
# At runtime: secr run -- node dist/server.js
# Or inject via your orchestrator's env var mechanism.
CMD ["node", "dist/server.js"]

Never COPY .env into a Docker image. Secrets should be injected at runtime via secr run or your orchestrator's native secret injection.

Quick Reference for Agent Prompts

When chatting with your AI agent, these one-liners keep it on track:

Situation	What to Say
Agent creates a .env file	"Delete that. We use secr. Reference process.env.KEY instead."
Agent hardcodes a secret	"Use process.env.SECRET_NAME, not a string literal."
Agent asks for a secret value	"I'll add it via secr set. Just use process.env.KEY_NAME in the code."
Setting up dev scripts	"Prefix with secr run --, e.g. secr run -- npm run dev"
Agent needs to know what secrets exist	"Run secr ls to see available keys."
New service needs credentials	"I'll add the secret. Use process.env.NEW_SERVICE_KEY."

Setup Checklist

Install secr CLI

npm i -g @secr/cli

Initialize project

secr init

Import existing .env

secr set --from-env .env && rm .env

Install pre-commit guard

secr guard install

Add .env* to .gitignore

echo ".env*" >> .gitignore

Add agent rules file

Create CLAUDE.md / .cursorrules / .windsurfrules

Update package.json scripts

Prefix dev/test with secr run --

Run a baseline scan

secr scan

AI agents + secr = fast and secure

Set up once, benefit on every session. Your agent will never leak a secret again.

Create Free Account Read: AI Security Pitfalls