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
GOOGLE_API_KEY=op(op://api-local/google/api-key)

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.

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.

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 AI CLI tool examples below for tool-specific setup.

AI CLI tool examples

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).

Claude

Claude Code is Anthropic’s CLI tool for AI-assisted coding.

Environment variable: ANTHROPIC_API_KEY. See supported env variables.

In a project, add to .env.schema:

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

varlock run -- claude

From any directory, personal schema at ~/.env.claude:

~/.env.claude

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

varlock run -p ~/.env.claude -- claude

Shell alias (optional):

alias vclaude='varlock run -p ~/.env.claude --no-redact-stdout -- claude'

--no-redact-stdout keeps Claude’s own terminal output unredacted while secrets stay out of your shell history.

Opencode

Opencode is a provider-agnostic AI coding assistant that works in your terminal.

Environment variables:

• ANTHROPIC_API_KEY for Claude models
• OPENAI_API_KEY for OpenAI models
• OPENCODE_CONFIG path to custom config file (optional)

Auth configuration: run opencode auth login once. When prompted for an API key, paste an env reference instead:

{"env:ANTHROPIC_API_KEY"}

Your config file (~/.local/share/opencode/auth.json) should look like:

~/.local/share/opencode/auth.json

{
  "anthropic": {
    "type": "api",
    "key": "{env:ANTHROPIC_API_KEY}"
  }
}

In a project, add to .env.schema:

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

# @sensitive
OPENAI_API_KEY=op(op://api-local/openai/api-key)

varlock run -- opencode

# or with a specific model
varlock run -- opencode --model claude-3-5-sonnet

From any directory, personal schema at ~/.env.opencode:

~/.env.opencode

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

# @sensitive
OPENAI_API_KEY=op(op://api-local/openai/api-key)

varlock run -p ~/.env.opencode -- opencode

# or with a specific model
varlock run -p ~/.env.opencode -- opencode --model claude-3-5-sonnet

Shell alias (optional):

alias vopencode='varlock run -p ~/.env.opencode --no-redact-stdout -- opencode'

See the Opencode docs for more information.

Antigravity

Antigravity CLI is Google’s agent-first terminal experience, the successor to Gemini CLI, which has been phased out.

Launch command: agy

Authentication: Antigravity signs in via Google OAuth on first launch (credentials live in your system keyring).

varlock run -- agy

From any directory, personal schema at ~/.env.antigravity for project-agnostic defaults:

~/.env.antigravity

# @type=enum(development, staging, production)
APP_ENV=development

varlock run -p ~/.env.antigravity -- agy

Shell alias (optional):

alias vagy='varlock run -p ~/.env.antigravity --no-redact-stdout -- agy'

See the Antigravity CLI getting started guide and installation & auth docs for OAuth, enterprise, and headless setup.

---

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 the full Varlock llms.txt. In Cursor, this is accomplished via ‘Add New Custom Docs’.

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.