varlock

Varlock

このスキルでは、varlock を使ってプロジェクトの環境変数とシークレットを安全に管理します。

ドキュメント: https://varlock.dev リポジトリ: https://github.com/dmno-dev/varlock

Varlock では、プロジェクトの環境変数の信頼できる唯一の情報源として、.env.example の代わりに .env.schema を使用します。スキーマ情報は、@decorator 形式のコメントで記述します。機密値は、Git の追跡対象外である .env.local ファイルに設定するか、環境変数として渡すか、関数を使って 1Password、Vault、AWS などのセキュアなバックエンドから読み込めます。

基本的な .env.schema の例：

# @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=

.env.schema はバージョン管理にコミットされるため、エージェントが読み取りや更新を行っても安全です。varlock CLI は、機密情報をマスキングしながら環境変数の読み込みと検証を行い、コマンドに環境変数を安全に渡すこともできます。

注意： varlock をスタンドアロンバイナリではなく package.json 経由でローカルにインストールしている場合は、パッケージマネージャー経由で実行してください。例：pnpm exec varlock load、bunx varlock load、npm exec varlock load。CLI コマンドを実行する前に、プロジェクトのパッケージマネージャーを確認してください。

重大：セキュリティルール

次のルールは必ず守ってください。

シークレットを公開しない

# NEVER do these - exposes secrets to agent context
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

ユーザーが機密値を確認する必要がある場合は、varlock reveal VAR_NAME を実行するよう伝えてください。

ファイルアクセスのルール

• 読み取りと編集が安全なファイル： .env.schema および Git にコミットされているその他の .env ファイル（通常は .env.development など、環境固有のファイル）
• 読み取りも編集も禁止： .env、.env.local、.env.[env].local、その他 Git の追跡対象外となっている値やオーバーライド用のファイル。暗号化されていないシークレットが含まれている可能性があります
• 生のシークレット値をコード、コメント、チャットに記録したり、引用したりしないでください

機密性に関するルール

• @sensitive が付いている項目は、ユーザーへの確認なしにそのデコレーターを削除してはいけません
• シークレット値は、ユーザー自身がローカルまたは Git の追跡対象外の環境変数ファイル、あるいはシークレットプロバイダー（1Password、AWS など）で編集するよう依頼してください。シークレットを自分で入力してはいけません

ユーザーから「.env ファイルを見せて」と頼まれた場合

.env や .env.local を直接読み取ってはいけません。代わりに varlock load を実行してマスキングされた値を表示するか、.env.schema を読み取ってスキーマを表示してください。環境変数ファイルを直接読み取ると、シークレットが公開される可能性があることを説明してください。

ユーザーから「シークレットを更新／設定して」と頼まれた場合

シークレット値を自分で書き込んではいけません。ユーザーに次のいずれかを行うよう伝えてください。

1. シークレットプロバイダー（1Password、AWS など）で更新してもらい、その後、連携方法をサポートする
2. .env.local ファイルの値を手動で編集してもらう

• できれば、値に varlock(prompt) を使って暗号化し、その後 varlock load を実行して入力を促す方法をおすすめします

その後、varlock load --agent を実行して検証してください。

ファイルの役割

ファイル	役割	エージェントが編集可能か？
.env.schema	スキーマ、デフォルト値、デコレーター、説明	はい
.env.[env]	環境固有の追跡対象設定（例：.env.production）	はい
.env, .env.local	ローカル／Git の追跡対象外の値とオーバーライド	いいえ — ユーザーに編集を依頼
.env.[env].local	環境固有のローカルオーバーライド（Git の追跡対象外）	いいえ — ユーザーに編集を依頼
.env.example	従来のサンプルファイル。スキーマに移行してください	ユーザーと確認

.env.schema および追跡対象の環境固有ファイルが Git の追跡対象外になっていないことを確認してください。必要に応じて、.gitignore に !.env.schema、!.env.production などを追加します。

環境固有のファイルと優先順位

.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 が最優先されます。

KEY= のように値を指定しない場合、値は設定されないため、優先順位の低いファイルの値は上書きされません。空文字列で上書きするには KEY="" を使用してください。

スキーマ構文

ルートデコレーター（ファイルヘッダー）

ルートデコレーターは、ファイルの先頭にある最初の項目より前のコメントブロックに記述します。通常、ヘッダーと項目の間は # --- の区切り線で分けます。

デコレーター	用途	ない場合
@currentEnv=$VAR	アクティブな環境を決定する項目を指定します	—
@defaultRequired=bool|infer	このファイル内の項目のデフォルトの必須状態を指定します	true
@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 ファイルまたはディレクトリからスキーマ／値をインポートします	—
@plugin(@varlock/name-plugin)	プラグインを読み込みます	—
@setValuesBulk(resolver)	外部ソースから複数の値を注入します	—
@disable	このファイルの読み込みを無効にします（=forEnv(test) を使用できます）	false

• @defaultSensitive のデフォルトは true です。明示的に @public または @sensitive=false とマークされていない限り、すべての項目は機密扱いになります。デフォルトを反転するには @defaultSensitive=false を設定します。
• @defaultRequired=infer の場合、スキーマに値がある項目は必須、値がない項目は任意になります。このデコレーターがない場合、項目はデフォルトで必須になります。
• varlock init は生成するスキーマに @defaultRequired=infer と @defaultSensitive=false を書き込むため、ほとんどの既存プロジェクトでは、デコレーターがない場合の動作ではなく、これらの設定で実行されます。どちらを前提にするか判断する前に、ファイルヘッダーを確認してください。
• 項目のデフォルト（@defaultRequired、@defaultSensitive）は、同じファイル内で定義された項目にのみ適用されます。.env.local またはインポートしたファイルでのみ定義された項目は、ルートスキーマの設定にかかわらず、組み込みのデフォルト（必須、機密）に戻ります。
• @defaultSensitive=inferFromPrefix(PUBLIC_) の場合、キーが PUBLIC_ で始まる項目は機密扱いにならず、それ以外は機密扱いになります。
• @import() では、条件付きインポートに enabled=expr、任意のインポートに allowMissing=true を指定できます。

項目デコレーター

設定項目の直前にあるコメント行のデコレーターは、その項目に関連付けられます。空行があると関連付けは切れます。

デコレーター	用途
@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))。

一般的なデータ型（@type=）

string(startsWith=X)、string(matches=regex("^pattern$"))、number、boolean、url、email、port、enum(a, b, c)、ipAddress、semver

プレーンな string がデフォルトです。@type=string は追加せず、@type 自体を省略してください。特定の型や文字列の制約が必要な場合にのみ @type を使用します。https://varlock.dev/reference/data-types/ を参照してください。

リゾルバー関数（値）

静的な値の代わりに、項目でリゾルバー関数を使用できます。

# Reference another item ($VAR and ${VAR} are shorthand for ref(VAR))
FULL_URL=${API_URL}/v2/users

# Execute a CLI command
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, regex(".*"), preview, undefined, development)

# Check environment (based on @currentEnv)
# @required=forEnv(prod, staging)
PROD_ONLY_KEY=

主な関数：ref()、concat()、exec()、fallback()、if()、eq()、not()、and()、or()、isEmpty()、ifs()、remap()、forEnv()

https://varlock.dev/reference/functions/ を参照してください。

機密値の設定

主な方法は2つあります。併用することもできます。

アプローチ 1：プラグイン（バージョン管理されたシークレット参照）

Varlock のプラグインを使うと、外部プロバイダーのシークレットを .env.schema から宣言的に直接参照できます。実際の値は読み込み時に取得されるため、参照情報は安全にコミットできます。

# @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)

各プラグインはそれぞれ独自のリゾルバー関数（1Password の op()、AWS の awsSecret() など）を提供します。プラグインの一覧については以下のプラグインを、設定の詳細については https://varlock.dev/guides/plugins/ をご覧ください。

アプローチ 2：varlock() によるローカル暗号化（Git で無視されるファイル）

.env.local など、Git で無視されるファイルにローカル保存するシークレットには、varlock() 関数を使ってデバイスローカルで暗号化し、平文で保存されないようにします。

# 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
# which is encrypted and written back to this file automatically
NEW_SECRET=varlock(prompt)

値を暗号化する方法：

• 対話型プロンプト： 値を varlock(prompt) に設定して varlock load を実行すると、ユーザーに安全な方法で入力が求められ、暗号化された値でプレースホルダーが自動的に置き換えられます
• 一括で暗号化： varlock encrypt --file .env.local は、機密性の高い平文の値をすべてその場で暗号化します
• 単一の値を暗号化： varlock encrypt は値の入力を求め、コピーして貼り付けられる暗号化結果を出力します
• 標準入力からパイプ： 生成されたキーや別のツールから読み取った値など、コンテキストに露出させずに値を暗号化するには、値を varlock encrypt にパイプします：

  some-cli-that-outputs-secret | varlock encrypt
  # prints: SOME_SENSITIVE_KEY=varlock("local:<encrypted>")
  

  これにより、平文のシークレットがシェルの履歴やエージェントのコンテキストに残りません。

macOS（Secure Enclave + Touch ID）、Windows（DPAPI + Windows Hello）、Linux（TPM2）ではハードウェアを利用して暗号化されます。すべてのプラットフォームでファイルベースのフォールバックも利用できます。macOS では、システムのキーチェーンに値を保存する組み込みの代替手段として keychain() も利用できます。

https://varlock.dev/guides/local-encryption/ をご覧ください。

構成

環境変数の構成を設計する前に、リポジトリの構造をユーザーに確認してください。

単一プロジェクト： 通常はリポジトリのルートに .env.schema を 1 つ置けば十分です。

モノレポ／複数アプリ： @import() を使って共通の設定を共有します：

# Import shared config from root (directory form: also loads root .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

• ルートスキーマ — 共有サービス URL、組織全体のデフォルト値、共通のキー
• アプリごとのスキーマ — アプリ固有の項目を定義し、ルートや兄弟スキーマから必要なものをインポートします
• インポートは明示的に記述し、循環インポートは避けます

ルートとパッケージのどちらに各値を配置するか、どの環境を使用するかをユーザーと相談してください。

https://varlock.dev/guides/import/ をご覧ください。

プラグイン

プラグインは、外部シークレットプロバイダー向けのリゾルバー関数、データ型、デコレーターを追加します。.env.schema で @plugin() を使ってインストールします：

# @plugin(@varlock/1password-plugin)

JS プロジェクトでは、npm パッケージもインストールしてください。スタンドアロンバイナリでは、バージョンを固定します：@plugin(@varlock/[email protected])。

利用可能なプラグイン： 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（組み込み）。

各プラグインの設定方法については https://varlock.dev/plugins/overview/ をご覧ください。

統合（フレームワーク／ランタイム）

プロジェクトのフレームワークに対応する公式の統合を選択してください。推測で選ばないでください。https://varlock.dev/integrations/overview/ で、該当するガイド（Next.js、Vite、Astro、SvelteKit、Bun、Cloudflare、Expo など）を確認してください。

一般的な手順：

1. varlock がインストールされていることを確認します（varlock init --agent または既存の依存関係）
2. 統合ガイドに従い、ビルド／開発時の設定、生成される型、必要な設定を行います
3. 場当たり的に process.env を使うのではなく、統合で推奨されているエントリーポイント（varlock/auto-load、Vite プラグインなど）を優先します

フレームワークの統合が有効な場合、環境変数の読み込みと注入は自動的に処理されます。フレームワーク独自の開発／ビルドコマンドに varlock run は不要です。統合の対象外となる他のスクリプトやツール（単発のマイグレーション、CLI ツール、JavaScript 以外のコマンドなど）にのみ、varlock run -- <cmd> を使用してください。

dotenv からの移行： dotenv/config または dotenvx run を varlock の同等機能に置き換えます。https://varlock.dev/guides/migrate-from-dotenv/ を参照してください。

JavaScript 以外のアプリ／サービス： varlock run を使用するか、varlock load --format shell をパイプで渡してください。https://varlock.dev/integrations/other-languages/ を参照してください。

セットアップ

varlock のインストール：

• JavaScript プロジェクト： 開発用依存関係としてインストールします。npm install -D varlock（または bun add -D varlock、pnpm add -D varlock）
• スタンドアロンバイナリ（JavaScript 以外、またはグローバルでの使用）： https://varlock.dev/getting-started/installation/ を参照してください。

はじめに：

1. varlock init --agent を実行し、既存の .env／.env.example ファイルから初期 .env.schema を自動生成します
2. 生成されたスキーマをユーザーと一緒に確認します。init のヒューリスティックによる生成結果は下書きであり、最終版ではありません
3. 必要に応じて、このスキルをインストールします：
   • 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 で更新します

スキーマのチェックリスト

init の実行後、または .env.schema の編集時：

1. 自動生成された項目を確認します。ヒューリスティックによる生成結果は最終版ではありません
2. 名前だけでは内容が分からない項目には説明コメントを追加します
3. 通常の文字列以外の場合にのみ @type を設定します（@type=string は省略します）
4. 必要に応じて @required／@optional を指定します（またはルートの @defaultRequired を調整します）
5. シークレット、キー、トークン、認証情報に @sensitive が設定されていることをユーザーと確認します
6. 有用な値を @example に移し、ダミーのプレースホルダーは削除します
7. 必要に応じて @docs() リンクを追加します
8. デフォルト値をスキーマに移した後、他の .env ファイルから重複する値を削除します

検証の反復

スキーマの変更後：

varlock load --agent

検証エラーに基づいて、スキーマと追跡対象の環境変数ファイルを修正します。スキーマエラーを解消するために、Git で無視されている .local の値ファイルを変更しないでください。シークレットをローカルで更新するようユーザーに依頼してください。

CLI クイックリファレンス

すべてのフラグとオプションを確認するには、varlock --help または varlock <command> --help を実行してください。

コマンド	使用する場面
varlock init --agent	対話なしで varlock をセットアップするとき
varlock load --agent	設定を安全に検証するとき（JSON、機密値はマスキングされます）
varlock load	人が読みやすい形式で検証結果をユーザーに表示するとき
varlock run -- <cmd>	解決済みの環境変数をプロセスに注入するとき
varlock printenv VAR_NAME	解決済みの環境変数を1つ、標準出力に表示するとき
varlock reveal	機密値を安全に表示／コピーするとき
varlock encrypt	値を暗号化するとき（単一の値、または一括処理用の --file）
varlock scan	ファイル内の漏えいしたシークレットをスキャンするとき（コミット前には --staged、設定には --install-hook）
varlock audit	スキーマとコードでの使用状況のずれを検出するとき
varlock codegen	スキーマからのコード生成を明示的に実行するとき（通常は自動実行されます。typegen は非推奨の別名です）
varlock lock	生体認証セッションをロックするとき（次回の復号時に再認証が必要です）
varlock freeze	デプロイ時に一度だけ値を解決し、アプリの起動元となる暗号化ファイルに保存するとき（実行時に _VARLOCK_USE_FROZEN_ENV=1 を設定）

既存のプロジェクトを更新する

.env.schema を信頼できる唯一の情報源として維持します。編集するのはスキーマと追跡対象の .env.[env] ファイルだけにし、git で無視される .local ファイルは編集しないでください。

1. スキーマの変更 — .env.schema の項目を追加・削除・名前変更し、コードをそれに合わせて更新してから、varlock load --agent を実行します
2. シークレット — スキーマ内の機密値は空のままにし、ローカルまたはシークレットプロバイダーで設定するようユーザーに依頼します
3. プラグイン — ヘッダーに @plugin() を追加し、利用できる場合は生の exec() よりもプラグインリゾルバーを優先します
4. コード生成 — @generateTsTypes（およびその他の @generate*Env デコレーター）はデフォルトで読み込み時に実行されます。明示的に制御する必要がある場合は、auto=false と varlock codegen を使用します
5. コミット前 — varlock load --agent、続いて varlock scan --staged を実行します。キーの名前を変更した場合や、ずれが疑われる場合は varlock audit も実行します

詳しいパターンについては、スキーマ、シークレット、モノレポを参照してください。

高度な使い方

• 複数の環境：https://varlock.dev/guides/environments/
• デプロイ：フレームワーク統合では解決済みの値をビルド時に埋め込みます。ビルド工程のないアプリ（Elysia、Hono、Fastify）では varlock freeze を使用します：https://varlock.dev/guides/frozen-env/
• 大規模なスキーマを @import で分割：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/

ドキュメント

このスキルの範囲を超える詳細については、AI ツールに Varlock Docs MCP ツールがインストールされている場合はそれを使用するか、https://varlock.dev/guides/schema から参照してください。