AI Tools

Your .env.schema gives AI agents full context on your configuration (variable names, types, validation rules, descriptions), while your secret values never leave your machine or touch AI servers.

This solves two problems with AI-assisted development:

1. Secret exposure: AI tools read your project files, including .env files. With varlock, secrets are never stored in plain text. They’re fetched at runtime from secure providers.
2. AI-generated leaks: AI agents may hardcode secrets or log sensitive values in generated code. varlock scan catches these leaks before they’re committed, and runtime protection redacts secrets from logs and responses.

Securely inject secrets into AI CLI tools

Many AI coding assistants offer CLI tools that require API keys and other secrets. Instead of storing these secrets in plain text .env or .json files or exposing them in your shell history, use varlock to inject them securely at runtime. This applies both to config that might be required to bootstrap the tool itself, as well as things like MCP servers that require API keys.

1. Install varlock

If you haven’t already, install varlock on your system.

2. Create an environment schema

Define your API keys and secrets in your .env.schema file. Mark sensitive values appropriately:

.env.schema

# @plugin(@varlock/1password-plugin)
# @initOp(allowAppAuth=true)
# ---
# @sensitive @required
OPENAI_API_KEY=op(op://api-local/openai/api-key)

# @sensitive @required
ANTHROPIC_API_KEY=op(op://api-local/anthropic/api-key)

# @sensitive @required
KIMI_API_KEY=op(op://api-local/kimi/api-key)

# @sensitive @required
GOOGLE_API_KEY=op(op://api-local/google/api-key)

Tip

You can use any secrets provider you want, but we like 1Password since it uses biometric authentication for local access. All the examples in this guide use the 1Password plugin (op()) to show more real world examples. See that page for plugin setup and auth options.

Store the actual secret values in your preferred secret provider. The examples above use the 1Password plugin’s op() resolver, but any provider plugin works the same way (AWS Secrets Manager, and more). If you’d rather not depend on an external provider, keep encrypted values in a gitignored .env.local using device-local encryption. See also the Secrets guide.

3. Run your tool via varlock run

Execute your AI CLI tool through varlock to securely inject environment variables:

varlock run -- <your-cli-command>

See the tool-specific guides below for setup details.

AI CLI tool guides

Popular AI coding CLIs differ in which env vars they need and how they authenticate. Varlock supports two patterns:

• Project setup: define secrets in the repo’s .env.schema (steps 1-2 above) and run varlock run -- <tool> from the project directory.
• Personal setup: keep a schema in your home directory (for example ~/.env.claude) and pass it with -p when launching a tool from any directory (usually using an alias).

Varlock does not auto-load a global schema (that would make two developers’ machines behave differently for the same repo).

Aider Git-aware terminal pair programmer with provider API keys

Antigravity CLI Run agy with validated env via varlock

Claude Code Inject ANTHROPIC_API_KEY with varlock run

Codex Inject OPENAI_API_KEY / CODEX_API_KEY for Codex CLI

Crush Charm's multi-provider terminal coding agent

Goose Block's MCP-native open-source agent

Kimi Inject KIMI_API_KEY into Kimi Code CLI

Opencode Provider-agnostic CLI with env-referenced API keys

---

Install the Varlock skill

Give your AI agent project-scoped instructions for working with Varlock: security rules, schema checklists, and CLI guidance. Install using one of:

skills

Install with the skills CLI (recommended):

npx skills add dmno-dev/varlock

The CLI detects your installed agents and installs to the correct skills directory (Cursor, Claude Code, Codex, Copilot, OpenCode, and 50+ others).

Target a specific agent with -a:

npx skills add dmno-dev/varlock -a cursor -a claude-code -y

Update later with:

npx skills update varlock

GitHub CLI

Install with gh skill (requires GitHub CLI v2.90+):

gh skill install dmno-dev/varlock varlock

Target a specific agent and scope:

gh skill install dmno-dev/varlock varlock --agent cursor --scope project

Update later with:

gh skill update varlock

Agent mode

Varlock provides a non-interactive --agent flag for init and load, designed for AI coding assistants running commands on your behalf.

varlock init --agent

Use this when an AI agent is setting up Varlock in a project:

varlock init --agent

In agent mode, init skips interactive confirmation prompts, uses deterministic defaults when multiple .env.example files are found, and prints schema review guidance for the agent to follow.

varlock load --agent

Use this to validate resolved config without exposing secret values in logs or agent transcripts:

varlock load --agent

Agent mode defaults to JSON output and redacts values marked @sensitive. It is not compatible with --format env or --format shell (which would expose raw values).

Drop the --agent flag when you need human-readable output to show the user directly.

Reading varlock output programmatically

When an agent needs to consume varlock output rather than show it to a user, prefer machine-readable formats and branch on exit codes:

• varlock load --agent: flat { "KEY": value } JSON on stdout with @sensitive values redacted. Safe to keep in a transcript.
• varlock load --agent --format json-full: the full serialized graph (sources, per-item validation state, sensitivity) with sensitive values redacted, for when you need to reason about why something is invalid, not just the values. Always keep --agent here: plain --format json-full emits raw secret values and must not go into an agent transcript.
• Exit codes: varlock load exits non-zero when config is invalid, varlock run forwards the child command’s exit code, and varlock scan exits 1 when it finds a leaked secret. Check the code instead of parsing prose.
• stdout vs stderr: pass --summary-stderr (or --summary-file) so the redacted human summary goes to stderr while stdout stays clean JSON for parsing.

See the CLI commands reference for the full output-format and exit-code details.

Tip

Use the Prompt Builder to generate a tailored setup prompt for your stack and AI tool.

Allowing schema files for AI tools

Most AI tools ignore .env.* files by default. To ensure your AI tool can access your environment schema, add the following to your .gitignore:

!.env.schema

If you use a tool with its own ignore file, check that tool’s documentation to see how it handles ignore files and make sure .env.schema is allowed.

Custom instructions and rules

The Varlock agent skill is the recommended way to give agents structured guidance for schema work and CLI usage.

You can also provide broader context with our llms.txt files. Start with varlock.dev/llms.txt, which summarizes what varlock is, when to use it, and links to topic-specific bundles (getting started and CLI reference, AI tools and MCP, integrations, plugins). The full docs are also available as a single file. In Cursor, this is accomplished via ‘Add New Custom Docs’.

Machine-readable discovery

Agents and tools can find everything above without scraping HTML:

• https://varlock.dev/llms.txt: docs index and “when to use” guidance
• https://varlock.dev/.well-known/ai-catalog.json: Agentic Resource Discovery manifest listing the docs MCP server, llms.txt files, skills, and the CLI
• https://varlock.dev/.well-known/agent-skills/index.json: Agent Skills index with SKILL.md files and digests
• https://varlock.dev/.well-known/mcp/server-card.json: MCP server card for the Docs MCP (also at /.well-known/mcp.json)
• Any docs page returns markdown when requested with an Accept: text/markdown header

If your tool supports custom rules, you can use our own varlock Cursor rule file from this repo as a starting point to create your own that is most suited to your workflow.

Scan for leaked secrets

AI agents can sometimes hardcode secret values or leak them into generated code. Use varlock scan to detect leaked secrets in your codebase:

# Scan the current directory for leaked secret values
varlock scan

# Scan specific paths
varlock scan ./src ./config

You can also set up varlock scan as a git pre-commit hook to automatically catch leaks before they’re committed:

# Add to your .git/hooks/pre-commit or use a hook manager like husky/lefthook
varlock scan --staged

This is especially useful when working with AI coding tools. The scan command compares your resolved secret values against your codebase to find any that may have been accidentally included in plain text.

Varlock Docs MCP

We also have a docs MCP server that allows you to search the Varlock docs. See more details here.