varlock

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Varlock

This skill helps securely manage env vars and secrets in your project using varlock.

Docs: https://varlock.dev Repo: https://github.com/dmno-dev/varlock

Varlock uses

.env.schema

(instead of

.env.example

) to provide a single source of truth for your project's env vars. Schema info is expressed using

@decorator

style comments. Sensitive values can be set in git-ignored

.env.local

files, passed in via the environment, or use functions to load from secure backends like 1Password, Vault, AWS, etc.

Basic

.env.schema

example:

env

undefined

本技能可帮助你借助Varlock安全管理项目中的环境变量（env vars）和密钥（secrets）。

文档: https://varlock.dev 代码仓库: https://github.com/dmno-dev/varlock

Varlock使用

.env.schema

（而非

.env.example

）作为项目环境变量的唯一可信来源。Schema信息通过

@decorator

风格的注释表达。敏感值可设置在Git忽略的

.env.local

文件中、通过环境传入，或使用函数从1Password、Vault、AWS等安全后端加载。

基础

.env.schema

示例：

env

undefined

@defaultSensitive=false @defaultRequired=infer

@currentEnv=$APP_ENV

@generateTsTypes(path=env.d.ts)

---

@type=enum(dev, staging, prod)

APP_ENV=dev

@type=url

API_URL=https://api.example.com

Description of this var

此变量的描述

@sensitive @required @type=string(startsWith=sk-)

@docs(https://xyzapi.com/docs/auth)

XYZ_API_KEY=


Your `.env.schema` is committed to version control and safe for agents to read and update. The `varlock` CLI helps load and validate env vars while masking anything sensitive, and can securely inject env vars into commands.

**NOTE:** If varlock is installed locally via `package.json` (not as a standalone binary), invoke it via your package manager — e.g., `pnpm exec varlock load`, `bunx varlock load`, `npm exec varlock load`. Check the project's package manager before running CLI commands.

XYZ_API_KEY=


你的`.env.schema`可提交至版本控制系统，且Agent可以安全地读取和更新它。`varlock` CLI可帮助加载和验证环境变量，同时屏蔽所有敏感内容，并能安全地将环境变量注入命令中。

**注意：** 如果Varlock是通过`package.json`本地安装的（而非独立二进制文件），需通过包管理器调用——例如`pnpm exec varlock load`、`bunx varlock load`、`npm exec varlock load`。运行CLI命令前请确认项目使用的包管理器。

CRITICAL: Security rules

重要安全规则

These rules are non-negotiable:

这些规则不容违反：

Do not expose secrets

禁止暴露密钥

bash

undefined

bash

undefined

NEVER do these - exposes secrets to agent context

绝对不要执行这些操作——会将密钥暴露给Agent上下文

cat .env cat .env.local echo $SECRET_KEY printenv | grep API

SAFE alternatives

安全替代方案

varlock load --agent # JSON output, sensitive values redacted varlock load # human-readable, sensitive values masked cat .env.schema # schema only, no secret values


If the user needs to see a sensitive value, tell them to run `varlock reveal VAR_NAME`.

varlock load --agent # JSON输出，敏感值已脱敏 varlock load # 人类可读格式，敏感值已屏蔽 cat .env.schema # 仅显示Schema，不含密钥值


如果用户需要查看敏感值，请告知他们运行`varlock reveal VAR_NAME`。

File access rules

文件访问规则

Safe to read and edit:
```
.env.schema
```
and any other git-committed
```
.env
```
files (usually env-specific files like
```
.env.development
```
)
Do not read or edit:
```
.env
```
,
```
.env.local
```
,
```
.env.[env].local
```
, or other gitignored value/override files — these may contain unencrypted secrets
Do not log or quote raw secret values in code, comments, or chat

可安全读取和编辑：
```
.env.schema
```
及其他Git已提交的.env文件（通常是特定环境的文件，如
```
.env.development
```
）
禁止读取或编辑：
```
.env
```
、
```
.env.local
```
、
```
.env.[env].local
```
或其他Git忽略的数值/覆盖文件——这些文件可能包含未加密的密钥
禁止记录或引用代码、注释或聊天中的原始密钥值

Sensitivity rules

敏感性规则

Items marked
```
@sensitive
```
must not have that decorator removed without confirming with the user
Ask the user to edit secret values in their local/gitignored env files or their secret provider (1Password, AWS, etc.) — never fill in secrets yourself

标记为
```
@sensitive
```
的项，未经用户确认不得移除该装饰器
请用户在本地/Git忽略的环境文件或密钥提供商（1Password、AWS等）中编辑敏感值——切勿自行填写密钥

When the user asks to "show me the .env file"

当用户要求“展示.env文件”时

Do not read

.env

.env.local

directly. Instead run

varlock load

to show masked values, or read

.env.schema

to show the schema. Explain that reading env files directly could expose secrets.

不要直接读取

.env

或

.env.local

。应运行

varlock load

显示已屏蔽的数值，或读取

.env.schema

显示Schema。向用户解释直接读取环境文件可能会暴露密钥。

When the user asks to "update/set a secret"

当用户要求“更新/设置密钥”时

Do not write secret values yourself. Tell the user to either:

Update it in their secret provider (1Password, AWS, etc.) and then help them wire it up
Edit the value in their
```
.env.local
```
file manually

ideally encrypt it by using
```
varlock(prompt)
```
as the value, then run
```
varlock load
```
to be prompted

Then run

varlock load --agent

to validate.

切勿自行写入密钥值。请告知用户选择以下方式之一：

在密钥提供商（1Password、AWS等）中更新，然后帮助他们完成关联配置
手动在
```
.env.local
```
文件中编辑值

理想情况下，使用
```
varlock(prompt)
```
作为值进行加密，然后运行
```
varlock load
```
触发输入提示

之后运行

varlock load --agent

进行验证。

File roles

文件角色

File	Role	Agent may edit?
`.env.schema`	Schema, defaults, decorators, descriptions	Yes
`.env.[env]`	Environment-specific tracked config (e.g. `.env.production` )	Yes
`.env` , `.env.local`	Local/gitignored values and overrides	No — tell user to edit
`.env.[env].local`	Environment-specific local overrides (gitignored)	No — tell user to edit
`.env.example`	Legacy example file; migrate into schema	Review with user

Ensure

.env.schema

and tracked env-specific files are not gitignored (

!.env.schema

!.env.production

, etc. in

.gitignore

if needed).

文件	作用	Agent可编辑？
`.env.schema`	Schema、默认值、装饰器、描述	是
`.env.[env]`	特定环境的已跟踪配置（例如 `.env.production` ）	是
`.env` , `.env.local`	本地/Git忽略的数值和覆盖配置	否——请用户自行编辑
`.env.[env].local`	特定环境的本地覆盖配置（Git忽略）	否——请用户自行编辑
`.env.example`	旧版示例文件；需迁移至Schema	与用户确认后操作

确保

.env.schema

和已跟踪的特定环境文件未被Git忽略（如有需要，在

.gitignore

中添加

!.env.schema

、

!.env.production

等规则）。

Environment-specific files and precedence

特定环境文件与优先级

When

@currentEnv

is set in

.env.schema

(e.g.,

@currentEnv=$APP_ENV

), varlock automatically loads matching environment-specific files. Files are applied in increasing precedence order:

.env.schema

.env

.env.local

.env.[currentEnv]

.env.[currentEnv].local

process.env

For example, if

APP_ENV=staging

, then

.env.staging

and

.env.staging.local

will be loaded automatically if they exist. A value in

.env.local

overrides one in

.env.schema

, and

process.env

always wins.

当

.env.schema

中设置了

@currentEnv

（例如

@currentEnv=$APP_ENV

）时，Varlock会自动加载匹配的特定环境文件。文件按优先级递增顺序应用：

.env.schema

.env

.env.local

.env.[currentEnv]

.env.[currentEnv].local

process.env

例如，如果

APP_ENV=staging

，则会自动加载

.env.staging

和

.env.staging.local

（如果存在）。

.env.local

中的值会覆盖

.env.schema

中的值，而

process.env

始终拥有最高优先级。

Schema syntax

Schema语法

Root decorators (file header)

根装饰器（文件头）

Root decorators go in comment blocks at the top of the file, before the first item. A

# ---

divider usually separates the header from items.

Decorator	Purpose	Default
`@currentEnv=$VAR`	Sets which item determines the active environment	—
`@defaultRequired=bool\|infer`	Default required state for items in this file	`infer`
`@defaultSensitive=bool\|inferFromPrefix(PREFIX)`	Default sensitive state for items in this file	`true`
`@generateTsTypes(path=./env.d.ts)`	Auto-generate TypeScript env declarations (deprecated alias: `@generateTypes(lang=ts)` )	—
`@generatePythonEnv` / `@generateRustEnv` / `@generateGoEnv` / `@generatePhpEnv` / `@generateJavaEnv` / `@generateCsharpEnv` `(path=...)`	Generate a typed env module for that language	—
`@import(path, ...keys?)`	Import schema/values from another .env file or directory	—
`@plugin(@varlock/name-plugin)`	Load a plugin	—
`@setValuesBulk(resolver)`	Inject multiple values from an external source	—
`@disable`	Disable loading this file (can use `=forEnv(test)` )	`false`

```
@defaultSensitive
```
defaults to
```
true
```
— all items are sensitive unless explicitly marked
```
@public
```
or
```
@sensitive=false
```
. Set
```
@defaultSensitive=false
```
to flip the default.
```
@defaultRequired=infer
```
(the default): items with a value in the schema are required, items without are optional
```
@defaultSensitive=inferFromPrefix(PUBLIC_)
```
: items with keys starting with
```
PUBLIC_
```
are not sensitive, all others are
```
@import()
```
accepts
```
enabled=expr
```
for conditional imports and
```
allowMissing=true
```
for optional imports

根装饰器位于文件顶部的注释块中，在第一个配置项之前。通常使用

# ---

分隔符将文件头与配置项分开。

装饰器	用途	默认值
`@currentEnv=$VAR`	设置哪个配置项决定当前激活的环境	—
`@defaultRequired=bool\|infer`	此文件中配置项的默认必填状态	`infer`
`@defaultSensitive=bool\|inferFromPrefix(PREFIX)`	此文件中配置项的默认敏感状态	`true`
`@generateTsTypes(path=./env.d.ts)`	自动生成TypeScript环境声明（已弃用别名： `@generateTypes(lang=ts)` ）	—
`@generatePythonEnv` / `@generateRustEnv` / `@generateGoEnv` / `@generatePhpEnv` / `@generateJavaEnv` / `@generateCsharpEnv` `(path=...)`	为对应语言生成类型化环境模块	—
`@import(path, ...keys?)`	从其他.env文件或目录导入Schema/值	—
`@plugin(@varlock/name-plugin)`	加载插件	—
`@setValuesBulk(resolver)`	从外部源注入多个值	—
`@disable`	禁用此文件的加载（可使用 `=forEnv(test)` ）	`false`

```
@defaultSensitive
```
默认值为
```
true
```
——所有配置项均为敏感项，除非显式标记
```
@public
```
或
```
@sensitive=false
```
。设置
```
@defaultSensitive=false
```
可反转默认规则。
```
@defaultRequired=infer
```
（默认值）：Schema中有值的配置项为必填项，无值的为可选项
```
@defaultSensitive=inferFromPrefix(PUBLIC_)
```
：以
```
PUBLIC_
```
开头的配置项为非敏感项，其余为敏感项
```
@import()
```
支持
```
enabled=expr
```
实现条件导入，
```
allowMissing=true
```
实现可选导入

Item decorators

配置项装饰器

Decorators in comment lines directly preceding a config item are attached to that item. A blank line breaks the association.

Decorator	Purpose
`@required` / `@optional`	Override default required state
`@sensitive` / `@public`	Override default sensitive state
`@type=dataType`	Set validation/coercion type
`@example="value"`	Example value (for docs, not used at runtime)
`@docs(url)` or `@docs(label, url)`	Link to related documentation (can be used multiple times)
`@icon=collection:name`	Iconify icon ID for generated docs
`@auditIgnore`	Suppress "unused in code" warning from `varlock audit`

Decorator values can use resolver functions:

@required=forEnv(prod)

@sensitive=not(forEnv(dev))

直接位于配置项之前的注释行中的装饰器会关联到该配置项。空行将中断这种关联。

装饰器	用途
`@required` / `@optional`	覆盖默认必填状态
`@sensitive` / `@public`	覆盖默认敏感状态
`@type=dataType`	设置验证/转换类型
`@example="value"`	示例值（用于文档，运行时不使用）
`@docs(url)` 或 `@docs(label, url)`	关联相关文档链接（可多次使用）
`@icon=collection:name`	用于生成文档的Iconify图标ID
`@auditIgnore`	抑制 `varlock audit` 产生的“代码中未使用”警告

装饰器值可使用解析函数：

@required=forEnv(prod)

、

@sensitive=not(forEnv(dev))

。

Common data types (

@type=

)

常用数据类型（

@type=

）

string(startsWith=X)

string(matches=/regex/)

number

boolean

url

email

port

enum(a, b, c)

ipAddress

semver

Plain

string

is the default — do not add

@type=string

, just omit

@type

entirely. Only use

@type

when you need a specific type or string constraints. See https://varlock.dev/reference/data-types/

string(startsWith=X)

、

string(matches=/regex/)

、

number

、

boolean

、

url

、

email

、

port

、

enum(a, b, c)

、

ipAddress

、

semver

默认类型为普通

string

——无需添加

@type=string

，直接省略

@type

即可。仅当需要特定类型或字符串约束时才使用

@type

。详情请见https://varlock.dev/reference/data-types/

Resolver functions (values)

解析函数（值）

Instead of static values, items can use resolver functions:

env

undefined

配置项可使用解析函数替代静态值：

env

undefined

Reference another item ($VAR and ${VAR} are shorthand for ref(VAR))

引用另一个配置项（$VAR和${VAR}是ref(VAR)的简写）

FULL_URL=${API_URL}/v2/users

Execute a CLI command

执行CLI命令

SECRET=exec(

op read "op://vault/item/field"

)

SECRET=exec(

op read "op://vault/item/field"

)

Conditional logic

条件逻辑

API_URL=if(eq($APP_ENV, prod), https://api.example.com, http://localhost:3000)

First non-empty value

第一个非空值

FALLBACK_VAR=fallback($PRIMARY, $SECONDARY, "default")

Map one value to another

值映射

APP_ENV=remap($CI_BRANCH, "main", production, /.*/, preview, undefined, development)

Check environment (based on @currentEnv)

检查环境（基于@currentEnv）

@required=forEnv(prod, staging)

PROD_ONLY_KEY=


Key functions: `ref()`, `concat()`, `exec()`, `fallback()`, `if()`, `eq()`, `not()`, `isEmpty()`, `ifs()`, `remap()`, `forEnv()`

See https://varlock.dev/reference/functions/

PROD_ONLY_KEY=


核心函数：`ref()`、`concat()`、`exec()`、`fallback()`、`if()`、`eq()`、`not()`、`isEmpty()`、`ifs()`、`remap()`、`forEnv()`

详情请见https://varlock.dev/reference/functions/

Setting sensitive values

设置敏感值

There are two main approaches — they can be used together.

主要有两种方法——可结合使用。

Approach 1: Plugins (version-controlled secret references)

方法1：插件（版本控制的密钥引用）

Varlock plugins let you declaratively reference secrets from external providers directly in your

.env.schema

. The references are safe to commit — actual values are fetched at load time.

env

undefined

Varlock插件允许你在

.env.schema

中直接声明式引用外部提供商的密钥。这些引用可安全提交——实际值会在加载时获取。

env

undefined

@plugin(@varlock/1password-plugin)

@initOp(token=$OP_TOKEN, allowAppAuth=forEnv(dev))

---

@sensitive @type=opServiceAccountToken

OP_TOKEN=

@sensitive

MY_SECRET=op(op://my-vault/item-name/field-name)


Each plugin provides its own resolver functions (e.g., `op()` for 1Password, `awsSecret()` for AWS). See [Plugins](#plugins) below for the full list and https://varlock.dev/guides/plugins/ for setup details.

MY_SECRET=op(op://my-vault/item-name/field-name)


每个插件都提供自己的解析函数（例如1Password的`op()`、AWS的`awsSecret()`）。完整插件列表请见下方【插件】部分，设置详情请见https://varlock.dev/guides/plugins/

Approach 2: Local encryption with

varlock()

(git-ignored files)

方法2：使用

varlock()

进行本地加密（Git忽略文件）

For secrets stored locally in git-ignored files like

.env.local

, use the

varlock()

function for device-local encryption so nothing is stored in plaintext:

env

undefined

对于存储在

.env.local

等Git忽略文件中的本地密钥，使用

varlock()

函数进行设备本地加密，避免明文存储：

env

undefined

Encrypted value — decrypted automatically at load time

加密值——加载时自动解密

API_KEY=varlock("local:<encrypted-payload>")

Prompt mode — on next

varlock load

, user is prompted to enter the value

提示模式——下次运行

varlock load

时，会提示用户输入值

which is encrypted and written back to this file automatically

输入的值会自动加密并写回此文件

NEW_SECRET=varlock(prompt)


**How to encrypt values:**
- **Interactive prompt:** Set the value to `varlock(prompt)` and run `varlock load` — the user will be prompted securely, and the encrypted value replaces the placeholder automatically
- **Encrypt in bulk:** `varlock encrypt --file .env.local` encrypts all sensitive plaintext values in-place
- **Encrypt a single value:** `varlock encrypt` prompts for a value and prints the encrypted result to copy/paste
- **Pipe via stdin:** To encrypt a value without exposing it in your context (e.g., a generated key or a value read from another tool), pipe it into `varlock encrypt`:
  ```bash
  some-cli-that-outputs-secret | varlock encrypt
  # prints: SOME_SENSITIVE_KEY=varlock("local:<encrypted>")

This keeps the plaintext secret out of shell history and agent context.

Encryption is hardware-backed on macOS (Secure Enclave + Touch ID), Windows (DPAPI + Windows Hello), and Linux (TPM2), with a file-based fallback on all platforms. On macOS,

keychain()

is also available as a built-in alternative that stores values in the system keychain.

See https://varlock.dev/guides/local-encryption/

NEW_SECRET=varlock(prompt)


**加密值的方法：**
- **交互式提示：** 将值设置为`varlock(prompt)`并运行`varlock load`——用户会收到安全提示，加密值会自动替换占位符
- **批量加密：** `varlock encrypt --file .env.local`会原地加密所有敏感明文值
- **加密单个值：** `varlock encrypt`会提示输入值并打印加密结果供复制粘贴
- **通过标准输入管道：** 为避免在上下文中暴露值（例如生成的密钥或从其他工具读取的值），可将其通过管道输入`varlock encrypt`：
  ```bash
  some-cli-that-outputs-secret | varlock encrypt
  # 输出：SOME_SENSITIVE_KEY=varlock("local:<encrypted>")

这样可防止明文密钥出现在Shell历史和Agent上下文中。

加密在macOS（Secure Enclave + Touch ID）、Windows（DPAPI + Windows Hello）和Linux（TPM2）上采用硬件加密支持，所有平台均提供基于文件的回退方案。在macOS上，还内置了

keychain()

替代方案，可将值存储在系统钥匙串中。

详情请见https://varlock.dev/guides/local-encryption/

Organization

项目组织

Ask the user how their repo is structured before designing the env layout.

Single project: one

.env.schema

at the repo root is usually enough.

Monorepo / multi-app: use

@import()

to share common config:

env

undefined

设计环境布局前，请询问用户其代码仓库的结构。

单项目： 通常在仓库根目录放置一个

.env.schema

即可。

单体仓库/多应用： 使用

@import()

共享通用配置：

env

undefined

Import shared config from root (directory form: also loads root .env / .env.local)

从根目录导入共享配置（目录形式：同时加载根目录的.env/.env.local）

@import(../../)

Import from a sibling service (specific keys only)

从兄弟服务导入（仅特定配置项）

@import(../api/.env.schema, pick=[SHARED_API_URL, SHARED_DB_HOST])

---

APP_PUBLIC_URL=http://localhost:3000


- **Root schema** — shared service URLs, org-wide defaults, common keys
- **Per-app schemas** — app-specific items, importing what they need from root/siblings
- Keep imports explicit; avoid circular imports

Discuss with the user: which values belong at the root vs per-package, which environments they use.

See https://varlock.dev/guides/import/

APP_PUBLIC_URL=http://localhost:3000


- **根Schema** —— 共享服务URL、组织级默认值、通用配置项
- **每个应用的Schema** —— 应用特定配置项，从根目录/兄弟服务导入所需内容
- 保持导入明确；避免循环导入

与用户讨论：哪些值属于根目录，哪些属于各个包，以及他们使用的环境。

详情请见https://varlock.dev/guides/import/

Plugins

插件

Plugins add resolver functions, data types, and decorators for external secret providers. Install with

@plugin()

in your

.env.schema

env

undefined

插件可为外部密钥提供商添加解析函数、数据类型和装饰器。在

.env.schema

中使用

@plugin()

安装：

env

undefined

@plugin(@varlock/1password-plugin)


In JS projects, also install the npm package. With the standalone binary, pin a version: `@plugin(@varlock/1password-plugin@1.2.3)`.

**Available plugins:** 1Password, AWS Secrets Manager, Azure Key Vault, Bitwarden, Dashlane, Doppler, Google Secret Manager, HashiCorp Vault, Infisical, Akeyless, KeePass, Keeper, Passbolt, Proton Pass, Pass, macOS Keychain (built-in).

See https://varlock.dev/plugins/overview/ for setup details for each plugin.


在JS项目中，还需安装对应的npm包。使用独立二进制文件时，需指定版本：`@plugin(@varlock/1password-plugin@1.2.3)`。

**可用插件：** 1Password、AWS Secrets Manager、Azure Key Vault、Bitwarden、Dashlane、Doppler、Google Secret Manager、HashiCorp Vault、Infisical、Akeyless、KeePass、Keeper、Passbolt、Proton Pass、Pass、macOS钥匙串（内置）。

每个插件的设置详情请见https://varlock.dev/plugins/overview/

Integrations (frameworks / runtimes)

集成（框架/运行时）

Pick the official integration for the project's framework — do not guess. Check https://varlock.dev/integrations/overview/ for the specific guide (Next.js, Vite, Astro, SvelteKit, Bun, Cloudflare, Expo, etc.).

Typical steps:

Confirm
```
varlock
```
is installed (
```
varlock init --agent
```
or existing dependency)
Follow the integration guide for build/dev wiring, generated types, and any required config
Prefer the integration's recommended entry point (
```
varlock/auto-load
```
, Vite plugin, etc.) over ad-hoc
```
process.env
```
usage

When a framework integration is active, it handles loading and injecting env vars automatically —

varlock run

is not needed for the framework's own dev/build commands. Only use

varlock run -- <cmd>

for other scripts or tools that the integration doesn't cover (e.g., one-off migrations, CLI tools, non-JS commands).

Migrating from dotenv: replace

dotenv/config

dotenvx run

with the varlock equivalent — see https://varlock.dev/guides/migrate-from-dotenv/

Non-JS apps/services: use

varlock run

or pipe

varlock load --format shell

— see https://varlock.dev/integrations/other-languages/

为项目框架选择官方集成——切勿猜测。具体指南请见https://varlock.dev/integrations/overview/（Next.js、Vite、Astro、SvelteKit、Bun、Cloudflare、Expo等）。

典型步骤：

确认已安装Varlock（
```
varlock init --agent
```
或已有依赖）
遵循集成指南完成构建/开发关联、生成类型及所需配置
优先使用集成推荐的入口点（
```
varlock/auto-load
```
、Vite插件等），而非临时的
```
process.env
```
用法

当框架集成激活时，它会自动处理环境变量的加载和注入——框架自身的开发/构建命令无需使用

varlock run

。仅当集成未覆盖其他脚本或工具（例如一次性迁移、CLI工具、非JS命令）时，才使用

varlock run -- <cmd>

。

从dotenv迁移： 将

dotenv/config

或

dotenvx run

替换为Varlock等效方案——详情请见https://varlock.dev/guides/migrate-from-dotenv/

非JS应用/服务： 使用

varlock run

或管道输出

varlock load --format shell

——详情请见https://varlock.dev/integrations/other-languages/

Setup

安装设置

Installing varlock:

JS projects: Install as a dev dependency —

npm install -D varlock

(or

bun add -D varlock

pnpm add -D varlock

)

Standalone binary (non-JS or global use): See https://varlock.dev/getting-started/installation/

Getting started:

Run
```
varlock init --agent
```
to auto-generate an initial
```
.env.schema
```
from existing
```
.env
```
/
```
.env.example
```
files
Review the generated schema with the user — init heuristics are a draft, not final

Optionally install this skill:

skills (recommended):

npx skills add dmno-dev/varlock

— update with

npx skills update varlock

GitHub CLI (v2.90+):

gh skill install dmno-dev/varlock varlock

— update with

gh skill update varlock

安装Varlock：

JS项目： 作为开发依赖安装——

npm install -D varlock

（或

bun add -D varlock

、

pnpm add -D varlock

）

独立二进制文件（非JS或全局使用）： 请见https://varlock.dev/getting-started/installation/

快速开始：

运行

varlock init --agent

从现有

.env

.env.example

文件自动生成初始

.env.schema

与用户一起审查生成的Schema——初始化启发式结果为草稿，并非最终版本

可选安装本技能：

skills（推荐）：

npx skills add dmno-dev/varlock

——更新使用

npx skills update varlock

GitHub CLI（v2.90+）：

gh skill install dmno-dev/varlock varlock

——更新使用

gh skill update varlock

Schema checklist

Schema检查清单

After init or when editing

.env.schema

Review auto-generated items — heuristics are not final
Add description comments where names are not self-explanatory
Set
```
@type
```
only when not a plain string (omit
```
@type=string
```
)
Mark
```
@required
```
/
```
@optional
```
as needed (or adjust root
```
@defaultRequired
```
)
Confirm
```
@sensitive
```
on secrets, keys, tokens, and credentials with the user
Move useful values to
```
@example
```
; delete dummy placeholders
Add
```
@docs()
```
links where helpful
Remove redundant values from other
```
.env
```
files after defaults move into the schema

初始化或编辑

.env.schema

后：

审查自动生成的配置项——启发式结果并非最终版本
对名称不直观的配置项添加描述注释
仅当不是普通字符串时设置
```
@type
```
（省略
```
@type=string
```
）
根据需要标记
```
@required
```
/
```
@optional
```
（或调整根
```
@defaultRequired
```
）
与用户确认密钥、令牌和凭证是否标记了
```
@sensitive
```
将有用的值移至
```
@example
```
；删除占位符
添加有用的
```
@docs()
```
链接
将默认值移至Schema后，从其他.env文件中删除冗余值

Validation loop

验证流程

After schema changes:

bash

varlock load --agent

Fix schema and tracked env files based on validation errors. Do not patch gitignored

.local

value files to silence schema errors — ask the user to update secrets locally.

Schema更改后：

bash

varlock load --agent

根据验证错误修复Schema和已跟踪的环境文件。请勿修改Git忽略的

.local

数值文件来消除Schema错误——请用户在本地更新密钥。

CLI quick reference

CLI快速参考

Run

varlock --help

varlock <command> --help

for full flags and options.

Command	Use when
`varlock init --agent`	Setting up varlock non-interactively
`varlock load --agent`	Validating config safely (JSON, sensitive values redacted)
`varlock load`	Showing human-readable validation to the user
`varlock run -- <cmd>`	Injecting resolved env into a process
`varlock printenv VAR_NAME`	Print a single resolved env var to stdout
`varlock reveal`	Securely view/copy a sensitive value
`varlock encrypt`	Encrypt values (single or `--file` for bulk)
`varlock scan`	Scan files for leaked secrets ( `--staged` for pre-commit, `--install-hook` to set up)
`varlock audit`	Detect drift between schema and code usage
`varlock codegen`	Explicitly trigger code generation from schema (usually triggered automatically; `typegen` is a deprecated alias)
`varlock lock`	Lock biometric session (requires re-auth on next decrypt)

运行

varlock --help

或

varlock <command> --help

查看完整参数和选项。

命令	使用场景
`varlock init --agent`	非交互式设置Varlock
`varlock load --agent`	安全验证配置（JSON格式，敏感值已脱敏）
`varlock load`	向用户展示人类可读的验证结果
`varlock run -- <cmd>`	将解析后的环境变量注入进程
`varlock printenv VAR_NAME`	将单个解析后的环境变量打印到标准输出
`varlock reveal`	安全查看/复制敏感值
`varlock encrypt`	加密值（单个值或使用 `--file` 批量加密）
`varlock scan`	扫描文件查找泄露的密钥（ `--staged` 用于预提交， `--install-hook` 用于设置钩子）
`varlock audit`	检测Schema与代码使用之间的差异
`varlock codegen`	从Schema显式触发代码生成（通常自动触发； `typegen` 为已弃用别名）
`varlock lock`	锁定生物识别会话（下次解密时需重新验证）

Updating an existing project

更新现有项目

Keep

.env.schema

as the source of truth. Edit schema and tracked

.env.[env]

files only — not gitignored

.local

files.

Schema changes — add/remove/rename items in
```
.env.schema
```
, update code to match, then
```
varlock load --agent
```
Secrets — leave sensitive values empty in schema; ask the user to set them locally or in their secret provider
Plugins — add
```
@plugin()
```
in the header and prefer plugin resolvers over raw
```
exec()
```
when available
Codegen —
```
@generateTsTypes
```
(and the other
```
@generate*Env
```
decorators) run on load by default; use
```
auto=false
```
and
```
varlock codegen
```
if you need explicit control
Before commit —
```
varlock load --agent
```
, then
```
varlock scan --staged
```
; run
```
varlock audit
```
if you renamed keys or suspect drift

See Schema, Secrets, and Monorepos for deeper patterns.

将

.env.schema

作为唯一可信来源。仅编辑Schema和已跟踪的

.env.[env]

文件——不要编辑Git忽略的

.local

文件。

Schema更改 —— 在
```
.env.schema
```
中添加/删除/重命名配置项，更新代码以匹配，然后运行
```
varlock load --agent
```
密钥 —— 在Schema中保留敏感值为空；请用户在本地或密钥提供商中设置
插件 —— 在文件头添加
```
@plugin()
```
，优先使用插件解析函数而非原生
```
exec()
```
代码生成 ——
```
@generateTsTypes
```
（及其他
```
@generate*Env
```
装饰器）默认在加载时运行；如果需要显式控制，使用
```
auto=false
```
并运行
```
varlock codegen
```
提交前 —— 运行
```
varlock load --agent
```
，然后运行
```
varlock scan --staged
```
；如果重命名了配置项或怀疑存在差异，运行
```
varlock audit
```

更深入的模式请见【Schema】(https://varlock.dev/guides/schema/)、【密钥】(https://varlock.dev/guides/secrets/)和【单体仓库】(https://varlock.dev/guides/monorepos/)

Advanced

进阶内容

Multiple environments: https://varlock.dev/guides/environments/
Split large schemas with
```
@import
```
: https://varlock.dev/guides/import/
Device-local encryption: https://varlock.dev/guides/local-encryption/
```
package.json
```
config (
```
varlock.loadPath
```
): https://varlock.dev/reference/cli-commands/
Built-in variables (
```
$VARLOCK_ENV
```
for auto-detecting environment): https://varlock.dev/reference/builtin-variables/

多环境：https://varlock.dev/guides/environments/
使用
```
@import
```
拆分大型Schema：https://varlock.dev/guides/import/
设备本地加密：https://varlock.dev/guides/local-encryption/
```
package.json
```
配置（
```
varlock.loadPath
```
）：https://varlock.dev/reference/cli-commands/
内置变量（
```
$VARLOCK_ENV
```
用于自动检测环境）：https://varlock.dev/reference/builtin-variables/

Docs

文档

For details beyond this skill, use the Varlock Docs MCP tool if installed in your AI tool, or refer to https://varlock.dev/guides/schema as a starting point.

如需本技能未涵盖的详细内容，若AI工具中已安装Varlock Docs MCP工具可直接使用，否则请从https://varlock.dev/guides/schema开始查阅相关文档。

varlock

Original

Translation

Varlock

Varlock

@defaultSensitive=false @defaultRequired=infer

@defaultSensitive=false @defaultRequired=infer

@currentEnv=$APP_ENV

@currentEnv=$APP_ENV

@generateTsTypes(path=env.d.ts)

@generateTsTypes(path=env.d.ts)

---

---

@type=enum(dev, staging, prod)

@type=enum(dev, staging, prod)

@type=url

@type=url

Description of this var

此变量的描述

@sensitive @required @type=string(startsWith=sk-)

@sensitive @required @type=string(startsWith=sk-)

@docs(https://xyzapi.com/docs/auth)

@docs(https://xyzapi.com/docs/auth)

CRITICAL: Security rules

重要安全规则

Do not expose secrets

禁止暴露密钥

NEVER do these - exposes secrets to agent context

绝对不要执行这些操作——会将密钥暴露给Agent上下文

SAFE alternatives

安全替代方案

File access rules

文件访问规则

Sensitivity rules

敏感性规则

When the user asks to "show me the .env file"

当用户要求“展示.env文件”时

When the user asks to "update/set a secret"

当用户要求“更新/设置密钥”时

File roles

文件角色

Environment-specific files and precedence

特定环境文件与优先级

Schema syntax

Schema语法

Root decorators (file header)

根装饰器（文件头）

Item decorators

配置项装饰器

Common data types (@type=)

常用数据类型（@type=）

Resolver functions (values)

解析函数（值）

Reference another item ($VAR and ${VAR} are shorthand for ref(VAR))

引用另一个配置项（$VAR和${VAR}是ref(VAR)的简写）

Execute a CLI command

执行CLI命令

Conditional logic

条件逻辑

First non-empty value

第一个非空值

Map one value to another

值映射

Check environment (based on @currentEnv)

检查环境（基于@currentEnv）

@required=forEnv(prod, staging)

@required=forEnv(prod, staging)

Setting sensitive values

设置敏感值

Approach 1: Plugins (version-controlled secret references)

方法1：插件（版本控制的密钥引用）

@plugin(@varlock/1password-plugin)

@plugin(@varlock/1password-plugin)

@initOp(token=$OP_TOKEN, allowAppAuth=forEnv(dev))

@initOp(token=$OP_TOKEN, allowAppAuth=forEnv(dev))

---

---

@sensitive @type=opServiceAccountToken

@sensitive @type=opServiceAccountToken

@sensitive

Common data types (
`@type=`
)

常用数据类型（
`@type=`
）

Approach 2: Local encryption with
`varlock()`
(git-ignored files)

方法2：使用
`varlock()`
进行本地加密（Git忽略文件）

Prompt mode — on next
`varlock load`
, user is prompted to enter the value

提示模式——下次运行
`varlock load`
时，会提示用户输入值