AGENT SKILL

varlock

Create and maintain `.env.schema` files in the varlock/@env-spec DSL. Use when adding env var definitions, migrating from `.env.example`, running varlock commands (init, load, run, encrypt, audit), debugging missing env vars, or wiring 1Password secrets.

License 许可
BSD-3-Clause
最近更新
2026-11-13
Stars
★ 0
Forks
0

01 前言 Front Matter

name
varlock
description
Create and maintain `.env.schema` files in the varlock/@env-spec DSL. Use when adding env var definitions, migrating from `.env.example`, running varlock commands (init, load, run, encrypt, audit), debugging missing env vars, or wiring 1Password secrets.

02 资源文件 1

03 SKILL.md 正文

Varlock

Varlock uses the @env-spec DSL: decorator-style comments on top of standard .env syntax. It declares environment variable schemas with types, validation, secrets integration, and defaults.

Full decorator/type reference: references/env-spec.md

File Structure

# This env file uses @env-spec - see https://varlock.dev/env-spec for more info
# @plugin(@varlock/1password-plugin@0.3.2)   ← root decorator (before ---)
# @initOp(allowAppAuth=true)
# ---                                         ← divider separates root from items

# --- Section Name ---                        ← organize items with dividers

# Human-readable description of what this var does
# @required @sensitive @example="sk-ant-api12345...."
ANTHROPIC_API_KEY=op(op://Private/ANTHROPIC_API_KEY/credential)

Key rules:

  • Root decorators (@plugin, @initOp, @defaultRequired, etc.) go before # ---
  • Item decorators (@required, @sensitive, @type, @example) go immediately above the key
  • ALL_CAPS keys only; no - or .; no spaces around =
  • Use # --- dividers to group related items

Common Patterns

1Password secrets (used in all projects)

# @plugin(@varlock/1password-plugin@0.3.2)
# @initOp(allowAppAuth=true)
# ---

# @required @sensitive
SECRET=op(op://VaultName/ItemName/credential)

API keys with examples

# @required @sensitive @example="sk-ant-api12345...."
ANTHROPIC_API_KEY=op(op://Private/ANTHROPIC_API_KEY/credential)

# @required @sensitive @example="AIxxxxxxx"
GEMINI_API_KEY=op(op://Private/GEMINI_API_KEY/credential)

Derived/constructed values

# Individual components
# @required
DB_HOST=localhost
# @required
DB_PORT=5432
# @required
DB_USER=myapp

# @required @sensitive
DB_PASSWORD=op(op://Private/DB_PASSWORD/credential)

# Constructed DSN — override if using a managed instance
# @required @sensitive
DATABASE_URL=postgresql://${DB_USER}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT}/myapp

Tool path discovery

OP_LOCATION=exec('which op')

Typed items

# @required @type=port
PORT=3000

# @required @type=url(prependHttps=true)
API_BASE_URL=https://api.example.com

# @required @type=enum(development, staging, production)
NODE_ENV=development

# @required @type=boolean
FEATURE_FLAG=false

CLI Commands

Command Purpose
varlock init Bootstrap .env.schema from existing .env files
varlock load Debug/validate — shows resolved values and errors
varlock run -- <cmd> Run a command with validated env vars injected
varlock encrypt --file .env.local Encrypt sensitive values in a file
varlock reveal Decrypt and show sensitive values
varlock lock Re-encrypt all decryptable values
varlock audit Report unused or undeclared vars

Invoke via package manager (JS/TS projects):

pnpm exec -- varlock load
npx varlock load
bunx varlock load

Standalone binary:

varlock load
varlock run -- python main.py

Installation

JS/TS project:

pnpm dlx varlock init   # installs + generates .env.schema from existing .env

Standalone binary: Download from https://varlock.dev/getting-started/installation

Decorator Quick Reference

See references/env-spec.md for the full reference. Most common:

Decorator Usage
@required Fail if value is empty/undefined
@optional Opposite of required
@sensitive Mask in logs/output
@example="val" Show example without setting a placeholder
@type=string Set type (string, number, boolean, url, enum, port, email, ip)
@docs(url) Link to documentation

04 同仓库更多 Skills