---
title: AI Tools
description: Your schema gives AI agents full context, while your secrets never touch AI servers
---
import { TabItem, Tabs } from "@astrojs/starlight/components";

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](/guides/mcp/) that require API keys.

### 1. Install varlock

If you haven't already, [install varlock](/getting-started/installation/) on your system.

### 2. Create an environment schema

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

```env-spec title=".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](/plugins/overview/). The examples above use the [1Password plugin](/plugins/1password/)'s `op()` resolver, but any provider plugin works the same way ([AWS Secrets Manager](/plugins/aws-secrets/), [and more](/plugins/overview/)). If you'd rather not depend on an external provider, keep encrypted values in a gitignored `.env.local` using [device-local encryption](/guides/local-encryption/). See also the [Secrets guide](/guides/secrets/#loading-secrets-from-external-sources).

:::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](/plugins/1password/) (`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:

```bash
varlock run -- <your-cli-command>
```

See [AI CLI tool examples](#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`](/reference/cli-commands/#run) 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).

<Tabs syncKey="ai-tool">
  <TabItem label="Claude">
    [Claude Code](https://docs.claude.com/en/docs/claude-code/overview) is Anthropic's CLI tool for AI-assisted coding.

    **Environment variable:** `ANTHROPIC_API_KEY`. See [supported env variables](https://docs.claude.com/en/docs/claude-code/settings#environment-variables).

    **In a project**, add to `.env.schema`:

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

    ```bash
    varlock run -- claude
    ```

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

    ```env-spec title="~/.env.claude"
    # @sensitive @required
    ANTHROPIC_API_KEY=op(op://api-local/anthropic/api-key)
    ```

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

    **Shell alias** (optional):

    ```bash
    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.
  </TabItem>

  <TabItem label="Opencode">
    [Opencode](https://opencode.ai/) 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:

    ```json title="~/.local/share/opencode/auth.json"
    {
      "anthropic": {
        "type": "api",
        "key": "{env:ANTHROPIC_API_KEY}"
      }
    }
    ```

    **In a project**, add to `.env.schema`:

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

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

    ```bash
    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-spec title="~/.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)
    ```

    ```bash
    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):

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

    See the [Opencode docs](https://opencode.ai/docs/) for more information.
  </TabItem>

  <TabItem label="Antigravity">
    [Antigravity CLI](https://antigravity.google/docs/cli-getting-started) is Google's agent-first terminal experience, the successor to [Gemini CLI](https://developers.googleblog.com/an-important-update-transitioning-gemini-cli-to-antigravity-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). 

    ```bash
    varlock run -- agy
    ```

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

    ```env-spec title="~/.env.antigravity"
    # @type=enum(development, staging, production)
    APP_ENV=development
    ```

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

    **Shell alias** (optional):

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

    See the [Antigravity CLI getting started guide](https://antigravity.google/docs/cli-getting-started) and [installation & auth docs](https://antigravity.google/docs/cli-overview) for OAuth, enterprise, and headless setup.
  </TabItem>
</Tabs>

---

## 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:

<Tabs>
  <TabItem label="skills">

Install with the [skills CLI](https://github.com/vercel-labs/skills) (recommended):

```bash
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](https://github.com/vercel-labs/skills#supported-agents)). 

Target a specific agent with `-a`:
```bash
npx skills add dmno-dev/varlock -a cursor -a claude-code -y
```

Update later with:

```bash
npx skills update varlock
```

  </TabItem>
  <TabItem label="GitHub CLI">

Install with [`gh skill`](https://github.blog/changelog/2026-04-16-manage-agent-skills-with-github-cli/) (requires GitHub CLI v2.90+):

```bash
gh skill install dmno-dev/varlock varlock
```

Target a specific agent and scope:

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

Update later with:

```bash
gh skill update varlock
```

  </TabItem>
</Tabs>

## 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:

```bash
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:

```bash
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](/reference/cli-commands/#load) for the full output-format and exit-code details.

:::tip
Use the [Prompt Builder](/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`:

```txt
!.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](#install-the-varlock-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`](https://varlock.dev/llms-full.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](https://github.com/dmno-dev/varlock/blob/main/.cursor/rules/varlock.mdc) 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:

```bash
# 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:

```bash
# 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](/guides/mcp/#docs-mcp).
