insforge.toml 是项目配置子集的声明性版本控制快照：身份验证策略、允许的重定向 URL、密码规则、SMTP、存储上传大小、实时和计划保留以及部署子域。CLI 提供针对此文件的三个命令：
config plan：将 insforge.toml 与链接项目进行比较。显示会发生什么变化。config apply：将差异推送到实时项目。按更改能力门控、环境解析的秘密、干运行模式。config export：拉取当前项目状态并写新的 insforge.toml。对从现有项目引导很有用。
您在存储库中保留一个 insforge.toml。要将其应用于不同环境（暂存、生产、队友的本地后端或自托管实例），请将 CLI 指向不同的项目（重新链接或使用 --project-id）。秘密通过 env(...) 引用从环境变量读取，所以文件本身保持免费的凭证并可以安全提交。
这在 InsForge Cloud 项目和自托管 OSS 部署上的工作方式相同。
所有示例使用 npx @insforge/cli。不要全局安装 CLI。
命令摘要
| 命令 | 目的 |
|---|
config plan | 显示 insforge.toml 和实时项目状态之间的差异 |
config apply | 将 insforge.toml 应用于实时项目 |
config apply --dry-run | 打印计划而不应用 |
config apply --auto-approve | 跳过交互式确认提示（在 --json 模式下需要） |
config export | 拉取实时配置并写 insforge.toml |
config export --force | 不确认覆盖现有 insforge.toml |
config plan 和 config apply 读取 insforge.toml；如果它存在于其他位置，通过 --file <path>。config export 写入文件；通过 --out <path> 将其写入自定义位置。
推荐工作流程
从现有项目引导
如果您已通过仪表板配置项目，导出一次以获得工作文件：这写 insforge.toml 反映当前后端状态。 提交它
检查 insforge.toml 进入版本控制。秘密通过 env(...) 引用，所以文件很安全。
应用
审查呈现的计划并确认。在 CI 中，通过 --auto-approve 和 --json。 在其他地方应用相同的文件
要将相同的配置推送到暂存或自托管后端，请将 CLI 指向其他项目并重新运行应用：在本地 shell 中因环境解析的不同秘密（SMTP 密码等），所以 TOML 不需要更改。 insforge.toml 覆盖什么
该文件镜像项目配置的精选子集，对于以声明方式管理有用的部分。任何不在此列表中的内容仍存在于仪表板和 API 上。
| 部分 | 键 |
|---|
[auth] | allowed_redirect_urls, require_email_verification, verify_email_method, reset_password_method, disable_signup |
[auth.password] | min_length, require_number, require_lowercase, require_uppercase, require_special_char |
[auth.smtp] | enabled, host, port, username, password, sender_email, sender_name, min_interval_seconds |
[storage] | max_file_size_mb |
[realtime] | retention_days |
[schedules] | retention_days |
[deployments] | subdomain |
null 文本，使用 retention_days = 0 禁用实时消息或计划执行日志的保留清理；config apply 为该值向后端发送 null。电子邮件模板、OAuth 提供商应用凭证、存储桶、实时通道、函数、部署环境变量和秘密不通过此文件管理。
完整示例：
config plan
plan 读取 insforge.toml，通过 /api/metadata 和存储、实时和计划的可选配置端点获取实时状态，然后打印呈现的差异。它也标记任何部分实时后端尚未公开（较旧的自托管版本等）。应用将跳过而不是失败整个运行。
在交互式会话中的每个 apply 之前使用 plan，并作为 CI 门来捕获意外漂移。
config apply
apply 运行与 plan 相同的差异，然后遍历更改集：
- 按更改能力门控。 每个更改根据后端的元数据或部分的配置端点进行检查。如果后端不支持部分（例如没有 SMTP 公开的较旧自托管实例），该部分会跳过带命名警告，其余更改仍然适用。
- 秘密解析。 TOML 中的
env(...) 引用在应用时从本地环境解析。如果缺少引用变量，命令在发送任何更新之前中止，所以后端不会被留下半配置。
- 按部分调度。 每个更改被发送到适当的后端端点（
/api/auth/config, /api/auth/smtp-config, /api/storage/config, /api/realtime/config, /api/schedules/config, /api/deployments/slug, 等）。更改是独立的，所以一个部分的失败不会回滚之前成功的部分。
标志：
--dry-run 打印计划并退出而不应用。--auto-approve 跳过交互式确认。当设置 --json 时需要，因为没有 TTY 用于提示。--file <path> 覆盖默认 ./insforge.toml 位置。
config export
export 拉取实时项目的可配置表面并将其写入 TOML 文件。使用它来：
- 从您一直通过仪表板配置的项目引导
insforge.toml。
- 通过导出到临时文件并比较来对手编辑进行比较。
- 快照配置在危险更改之前，以便您在需要回滚时重新应用快照。
export 写的文件与 CLI 从 apply 期望的形状相同，所以往返支持。
没有 --force，export 在交互式模式中拒绝覆盖现有文件，并在 --json 模式中曲面 OUTPUT_EXISTS 错误。
秘密引用
auth.smtp.password 和任何其他敏感字段可以表示为 env(VAR_NAME) 而不是文字值：
在应用时，CLI 从本地环境读取 SENDGRID_API_KEY，验证它的存在，并向后端发送解析的值。TOML 本身从不包含秘密，所以它可以提交。
这是让一个 insforge.toml 清洁地应用到多个环境的原因：开发和生产后端仅在哪个 SENDGRID_API_KEY 在您运行 apply 时范围内有所不同。
env(...) refs 在一个 TOML 中，是 apply 的目标在每次运行时重新发送解析的密码。这是 CLI 可以告诉后端”秘密可能已轮转，请更新”的唯一方式。没有 env(...) ref 的字段被视为保留现有。
何时使用这个
- 项目配置的版本控制。 重定向 URL、注册策略、密码策略、电子邮件验证模式、SMTP、存储上传大小和保留窗口存在在您的团队通过 PR 审查的文件中。
- 多环境奇偶校验。 一个 TOML，应用于开发、暂存和生产，保持支持的项目设置在各处对齐。环境特定值（子域、SMTP 凭证）通过
--project-id 覆盖和 env(...) refs 流。
- CI 驱动的配置更改。 从您的部署管道运行
config apply --auto-approve --json。与 config plan 结合作为 PR 检查，以便审查者看到合并在产品中会改变什么。
- 灾难恢复。 提交的
insforge.toml 是已知好的配置快照。在恢复项目后重新应用它以在几秒钟内使身份验证、SMTP、存储、保留和部署设置回到预期形状。
- 自托管和本地 OSS 开发。 运行
npx @insforge/cli link --api-base-url http://localhost:7130 --api-key <local-key> 针对 docker-compose 堆栈，然后将 CLI 的配置命令指向您的本地 OSS 实例，方式与您指向云的方式相同。
故障排除
Refusing to apply in --json mode without --auto-approve or --yes。 CLI 从不在非交互式运行中静默应用更改。明确通过 --auto-approve（或 -y）。
your backend doesn't expose <section>。 链接后端在一个版本上，该版本还没有相关的 API。其余的更改仍然适用。升级后端（或等待下一个版本）以应用该部分。
env(...) reference resolves to nothing。 当缺少引用环境变量时，CLI 在任何 API 调用之前中止。在您的 shell 或 CI 的秘密存储中设置变量并重新运行。
Slug is already taken。 deployments.subdomain 与同一后端上另一个项目的子域冲突。选择不同的值。
