env-to-fnox

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Migrate from .env to fnox + 1Password

从.env迁移到fnox + 1Password

This skill guides the migration from plaintext

.env

files to fnox with 1Password as the secret provider. fnox is provider-agnostic and supports multiple backends (1Password, AWS Secrets Manager, Azure Key Vault, HashiCorp Vault, age encryption, etc.).

本技能指导用户从明文.env文件迁移到以1Password作为密钥提供商的fnox系统。fnox是与提供商无关的工具，支持多种后端服务（1Password、AWS Secrets Manager、Azure Key Vault、HashiCorp Vault、age加密等）。

Prerequisites

前置条件

Before starting, verify:

1Password CLI is installed:
```
op --version
```
User is authenticated to 1Password:
```
op vault list
```
mise is installed (optional but recommended):
```
mise --version
```

开始前，请确认：

已安装1Password CLI：
```
op --version
```
用户已登录1Password：
```
op vault list
```
已安装mise（可选但推荐）：
```
mise --version
```

Migration Workflow

迁移工作流

Step 1: Analyze Existing .env

步骤1：分析现有.env文件

Read the existing

.env

file to understand what secrets need migration:

bash

cat .env

Categorize the secrets:

Cloud provider credentials (AWS_, ARM_, GOOGLE_*)
API tokens (CLOUDFLARE_, GITHUB_, etc.)
Application secrets (DATABASE_URL, API_KEY, etc.)
Configuration values (non-secret defaults like regions)

读取现有的.env文件，了解需要迁移的密钥：

bash

cat .env

对密钥进行分类：

云提供商凭证（AWS_、ARM_、GOOGLE_*）
API令牌（CLOUDFLARE_、GITHUB_等）
应用程序密钥（DATABASE_URL、API_KEY等）
配置值（非密钥默认值，如区域）

Step 2: Install fnox

步骤2：安装fnox

Install fnox via mise (recommended):

bash

mise use fnox

Or add to

mise.toml

toml

[tools]
fnox = "latest"

Initialize fnox configuration:

bash

mise exec -- fnox init
mise exec -- fnox provider add op 1password

通过mise安装fnox（推荐方式）：

bash

mise use fnox

或添加到

mise.toml

：

toml

[tools]
fnox = "latest"

初始化fnox配置：

bash

mise exec -- fnox init
mise exec -- fnox provider add op 1password

Step 3: Create 1Password Item

步骤3：创建1Password条目

Create a single 1Password item containing all secrets. Use the API Credential category for organization:

bash

op item create \
  --category="API Credential" \
  --title="project-name" \
  --vault="Private" \
  'Field Name[text]=value' \
  'Secret Field[password]=secret-value'

Field naming conventions:

Use descriptive names: "AWS Access Key ID" not "aws_key"
Use
```
[text]
```
for non-sensitive values (IDs, regions, emails)
Use
```
[password]
```
for sensitive values (secrets, tokens, keys)

Example for a typical project:

bash

op item create \
  --category="API Credential" \
  --title="myproject" \
  --vault="Private" \
  'AWS Access Key ID[text]=AKIA...' \
  'AWS Secret Access Key[password]=...' \
  'Database URL[password]=postgres://...' \
  'API Token[password]=...'

创建一个包含所有密钥的1Password条目，建议使用“API凭证”类别进行组织：

bash

op item create \
  --category="API Credential" \
  --title="project-name" \
  --vault="Private" \
  'Field Name[text]=value' \
  'Secret Field[password]=secret-value'

字段命名规范：

使用描述性名称：例如“AWS Access Key ID”而非“aws_key”
非敏感值（ID、区域、邮箱）使用
```
[text]
```
类型
敏感值（密钥、令牌、密钥）使用
```
[password]
```
类型

典型项目示例：

bash

op item create \
  --category="API Credential" \
  --title="myproject" \
  --vault="Private" \
  'AWS Access Key ID[text]=AKIA...' \
  'AWS Secret Access Key[password]=...' \
  'Database URL[password]=postgres://...' \
  'API Token[password]=...'

Step 4: Configure fnox.toml

步骤4：配置fnox.toml

Update

fnox.toml

to reference the 1Password item:

toml

[providers.op]
type = "1password"
vault = "Private"

[secrets]

更新

fnox.toml

以引用1Password条目：

toml

[providers.op]
type = "1password"
vault = "Private"

[secrets]

Format: ENV_VAR = { provider = "op", value = "item-title/Field Name" }

格式: ENV_VAR = { provider = "op", value = "item-title/Field Name" }

AWS_ACCESS_KEY_ID = { provider = "op", value = "myproject/AWS Access Key ID" } AWS_SECRET_ACCESS_KEY = { provider = "op", value = "myproject/AWS Secret Access Key" } DATABASE_URL = { provider = "op", value = "myproject/Database URL" }

Non-secret defaults don't need 1Password

非密钥默认值无需1Password

AWS_DEFAULT_REGION = { default = "us-east-1" }

undefined

AWS_DEFAULT_REGION = { default = "us-east-1" }

undefined

Step 5: Integrate with mise

步骤5：与mise集成

Update

mise.toml

to use fnox instead of

.env

toml

[tools]
fnox = "latest"

更新

mise.toml

以使用fnox替代.env：

toml

[tools]
fnox = "latest"

... other tools

... 其他工具

[env] _.source = "fnox export"


Remove the old `.env` reference:
```diff
- _.file = ".env"
+ _.source = "fnox export"

[env] _.source = "fnox export"


移除旧的.env引用：
```diff
- _.file = ".env"
+ _.source = "fnox export"

Step 6: Verify and Clean Up

步骤6：验证与清理

Test the configuration:

bash

undefined

测试配置：

bash

undefined

List configured secrets

列出已配置的密钥

mise exec -- fnox list

Verify a secret can be retrieved

验证能否获取密钥

mise exec -- fnox get AWS_ACCESS_KEY_ID

Test full environment

测试完整环境

mise exec -- printenv | grep AWS_


Once verified, delete the old `.env` file:

```bash
rm .env

Commit

fnox.toml

(it contains no secrets, only references):

bash

git add fnox.toml mise.toml
git commit -m "Migrate secrets from .env to fnox + 1Password"

mise exec -- printenv | grep AWS_


验证通过后，删除旧的.env文件：

```bash
rm .env

提交

fnox.toml

（该文件不含密钥，仅包含引用）：

bash

git add fnox.toml mise.toml
git commit -m "Migrate secrets from .env to fnox + 1Password"

fnox.toml Reference

fnox.toml参考

Provider Configuration

提供商配置

toml

undefined

toml

undefined

1Password

[providers.op] type = "1password" vault = "Private"

account = "my.1password.com" # Optional: specify account

account = "my.1password.com" # 可选：指定账户

Age encryption (for git-stored encrypted secrets)

Age加密（用于Git存储的加密密钥）

[providers.age] type = "age" recipients = ["age1..."]

AWS Secrets Manager

[providers.aws] type = "aws-sm" region = "us-east-1" prefix = "myapp/"

undefined

[providers.aws] type = "aws-sm" region = "us-east-1" prefix = "myapp/"

undefined

Secret Reference Formats

密钥引用格式

toml

[secrets]

toml

[secrets]

1Password: item-title/field-name

SECRET = { provider = "op", value = "myproject/Secret Field" }

1Password: full op:// URI

1Password: 完整op:// URI

SECRET = { provider = "op", value = "op://Vault/Item/Field" }

Default value (no provider needed)

默认值（无需提供商）

REGION = { default = "us-east-1" }

Age-encrypted value

Age加密值

SECRET = { provider = "age", value = "YWdlLWVu..." }

undefined

SECRET = { provider = "age", value = "YWdlLWVu..." }

undefined

Profiles for Multiple Environments

多环境配置文件

toml

[providers.op]
type = "1password"
vault = "Development"

[secrets]
DATABASE_URL = { provider = "op", value = "dev-db/url" }

[profiles.production.providers.op]
vault = "Production"

[profiles.production.secrets]
DATABASE_URL = { provider = "op", value = "prod-db/url" }

Use profiles with:

FNOX_PROFILE=production fnox export

toml

[providers.op]
type = "1password"
vault = "Development"

[secrets]
DATABASE_URL = { provider = "op", value = "dev-db/url" }

[profiles.production.providers.op]
vault = "Production"

[profiles.production.secrets]
DATABASE_URL = { provider = "op", value = "prod-db/url" }

使用配置文件：

FNOX_PROFILE=production fnox export

Troubleshooting

故障排除

"No configuration file found"

“未找到配置文件”

Run

fnox init

to create

fnox.toml

, or check that you're in the correct directory.

运行

fnox init

创建

fnox.toml

，或检查是否处于正确的目录中。

1Password authentication errors

1Password认证错误

Ensure you're signed in:

op signin

or check that "Integrate with other apps" is enabled in 1Password Settings > Developer.

确保已登录：

op signin

，或检查1Password设置>开发者中是否启用了“与其他应用集成”。

Secrets not loading in shell

密钥未在Shell中加载

If using mise, ensure

mise trust

has been run for the project directory.

如果使用mise，请确保已对项目目录运行

mise trust

。

fnox command not found after mise install

安装fnox后找不到命令

Use

mise exec -- fnox

or restart your shell to pick up the new PATH.

使用

mise exec -- fnox

或重启Shell以更新PATH。