insforge-cli

InsForge CLI

当有人需要后端，或通过 InsForge CLI 管理 InsForge 后端和云基础设施时使用此技能。对于从前端、后端或边缘函数调用 InsForge 的应用代码，请改用 insforge 应用集成技能。

核心规则

• 始终通过 npx @insforge/cli <command> 运行 CLI。不要安装或调用全局的 insforge 二进制文件。
• 如果项目已链接，使用当前链接的项目。仅在确实需要连接设置时才运行登录、项目创建、链接、项目发现、组织列表或云项目命令。
• 将 InsForge API 密钥视为完全访问的管理员密钥。仅限服务器使用，不要放在前端/公共环境变量中。
• 优先使用 CLI 命令和文档化的项目配置，而不是原始后端 HTTP 调用。如果 config apply 报告了不支持/跳过的字段，请展示该结果，而不是绕过 CLI 直接调用 API。
• 当需要结构化输出或非交互式值收集时，使用 --json。当用户已批准操作时，使用 --yes 确认提示。
• 在链接项目上开始非平凡任务时，先运行 npx @insforge/cli memory list（廉价，无 AI 调用），并在设计或调试前回忆与任务相关的任何标题。在决策和陷阱发生时立即用 memory remember 记录。参见 references/memory.md。

全局选项

标志	用途
--json	结构化 JSON 输出，跳过值收集提示（如文本/选择提示）。如果缺少任何必需值则报错。与 -y 结合用于也需要 Y/N 确认的破坏性命令。
-y, --yes	自动接受 Y/N 确认提示，如删除或覆盖提示。不会跳过值收集提示；请使用 --json 来实现。

退出码

代码	含义
0	成功
1	一般错误，包括函数调用返回的 HTTP 400+
2	未认证
3	项目未链接
4	资源未找到
5	权限被拒绝

环境变量

变量	用途
INSFORGE_ACCESS_TOKEN	覆盖存储的访问令牌
INSFORGE_PROJECT_ID	覆盖链接的项目 ID
INSFORGE_EMAIL	非交互式登录的邮箱
INSFORGE_PASSWORD	非交互式登录的密码

连接设置

如果任务需要项目访问且连接状态未知，从 npx @insforge/cli current 开始。当认证身份重要或 current 报告 CLI 未认证时，使用 npx @insforge/cli whoami。

如果未认证，运行 npx @insforge/cli login。如果没有链接项目，对于现有项目使用 npx @insforge/cli link，当用户要求新后端时使用 npx @insforge/cli create。在已预链接或预配置的工作流中，如 CI、本地测试项目、自动化或用户明确提供的项目上下文，直接使用该项目上下文。

命令路由

需求	CLI 区域	参考
登录、登出、当前用户	login, logout, whoami	references/login.md
创建/链接/列表/当前项目	create, link, list, current, metadata	references/create.md
项目生命周期：状态、重命名、删除、恢复、版本更新、实例调整大小、转移	projects	本文件
订阅/计划、积分、用量、付款历史、计费周期、计划升级、计费门户	billing, usage	本文件
组织和成员（创建、更新、邀请、角色）	orgs	本文件
项目备份（列表、最新、创建、重命名、删除、恢复）	backups	本文件
模式、SQL、RLS、触发器、索引、导入、导出	db	references/database/*
认证重定向、密码策略、SMTP、存储大小、实时/调度保留、子域名配置	config	references/config.md
存储桶和对象	storage	本文件
实时后端设置	db migrations	references/realtime.md
边缘函数	functions	references/functions-deploy.md
AI/OpenRouter 密钥设置	ai setup	本文件
代理记忆：项目事实、决策、跨会话的陷阱	memory	references/memory.md
Stripe/Razorpay 密钥、目录同步、Webhooks	payments	references/payments/overview.md
前端部署	deployments	references/deployments/deploy.md
自定义域名、Cloudflare Registrar、DNS 同步、SSL 验证	domains	references/deployments/domains.md
后端容器/服务	compute	references/compute-deploy.md
密钥/环境变量	secrets, deployment/compute env commands	本文件
定时任务	schedules	references/schedules.md
后端分支	branch	references/branch/overview.md, references/branch/merge.md, references/branch/reset.md
日志和健康检查	logs, diagnose	references/diagnostics.md
内置文档查询	docs	本文件
PostHog 设置	posthog setup	references/posthog.md
Apify 网页抓取器（连接、认证桥接、抓取、落地、调度）	webscraper apify	references/webscraper/apify.md

数据库工作流

当任务涉及非平凡的数据库工作时，在编写迁移前使用数据库参考：

• references/database/migrations.md - 迁移文件创建和应用工作流。
• references/database/query.md - 原始 SQL 执行和针对性检查。
• references/database/access-control.md - RLS、授权、递归安全辅助函数、ACL、受保护字段和公共投影。
• references/database/integrity.md - 约束、触发器、派生状态、生命周期守卫、仅追加历史记录和服务器维护字段。
• references/database/vector.md - pgvector 扩展、向量模式、距离运算符、索引和向量搜索 SQL/RPC 模式。
• references/database/export.md / references/database/import.md - 模式或数据导入/导出任务。

默认模式：

• 优先使用 npx @insforge/cli db migrations new <name> 加上迁移 SQL 文件来处理模式、授权、索引、触发器、函数和 RLS 策略更改。
• 使用 npx @insforge/cli db migrations up --all 应用迁移。
• 对于新的模式工作，在可行时将相关的 DDL 分组到一个迁移中。
• 当现有状态未知或命令失败时，使用针对性检查。
• 仅在迁移不合适时，使用 npx @insforge/cli db query <sql> 进行针对性检查和小的修正行/数据 SQL。
• 使用 npx @insforge/cli db rpc <fn> [--data <json>] 通过后端调用数据库函数。

公共模式范围：

• 对于通用的应用程序数据库工作，在 public 模式中创建和修改应用拥有的对象。
• 对 public 应用程序对象进行创建、修改、删除、授权、撤销、索引、触发器、函数、视图和策略更改。
• 不要创建自定义模式或写入 InsForge 管理/系统模式，如 auth、storage、realtime、payments、graphql、extensions、pg_catalog、information_schema 或 system，除非你正在处理该特定功能模块且其文档明确允许该操作。
• 允许从公共表或公共 RLS 策略中引用内置对象，如 auth.users(id) 和 auth.uid()；不要修改这些内置对象。
• 除非用户请求明确要求数据迁移、修复或测试设置，否则不要创建用户、种子业务行或运行应用程序 CRUD 工作流。

RLS 和访问控制：

• 使用 auth.uid() 或等效的认证身份表达式进行用户所有权检查。
• 同时添加 SQL 权限和 RLS 策略。策略不能替代 GRANT。
• 运行时角色在 public 表上具有广泛的默认 DML 权限，因此 RLS 可以决定行访问。如果表需要更窄的操作或列访问，请先显式 REVOKE 广泛权限，然后授予确切允许的操作或列。
• 为 INSERT 和 UPDATE 策略包含 WITH CHECK，以便写入操作不能创建用户不应拥有的行。
• 当直接策略连接可能通过其他 RLS 策略递归时，优先使用辅助函数进行跨表 RLS 检查。
• 从 RLS 策略中调用的查询 RLS 启用表的辅助函数应为 SECURITY DEFINER。
• 将 RLS 辅助函数放在 public 中，并使用模式限定引用，如 public.team_members 和 auth.uid()。
• 对于 ACL、受保护的所有者/租户/角色字段、字段级更新掩码、清理后的公共视图或递归敏感策略，在编写迁移前阅读 references/database/access-control.md。

完整性：

• 对于计数器、余额、最新指针、仅追加历史记录、状态转换、生命周期守卫、受保护删除、配额守卫、租约或触发器维护的列，在编写迁移前阅读 references/database/integrity.md。

向量：

• 对于 pgvector、向量搜索函数、分数语义、ANN 索引、混合排序、RAG 块检索、多向量搜索或嵌入版本选择，在编写迁移前阅读 references/database/vector.md。

项目和配置

项目命令：

• npx @insforge/cli create - 创建新项目。对于非交互式代理运行，使用 --json 和必需标志。参见 references/create.md。
• npx @insforge/cli link - 将当前目录链接到现有项目。
• npx @insforge/cli current - 显示当前链接的项目。
• npx @insforge/cli metadata --json - 当需要发现时检查后端元数据。

项目生命周期（除非给出 --project <id>，否则对链接项目操作）：

• npx @insforge/cli projects get [--project <id>] - 显示项目的当前状态、进行中的 operation_status、区域、实例类型和版本。在异步操作（恢复、版本更新、实例调整大小）后使用此命令轮询，直到 operation_status 清除。
• npx @insforge/cli projects update [--name <name>] [--domain <domain>] [--storage-size <gib>] [--project <id>] - 重命名或更改项目设置。
• npx @insforge/cli projects restore [--project <id>] - 将暂停的项目恢复上线。只有暂停的项目才能恢复。
• npx @insforge/cli projects update-version [--wait] [--project <id>] - 将后端更新到最新的 InsForge 版本（自动解析；如果已是最新则无操作）。会导致短暂重启。添加 --wait 以阻塞直到完成，而不是在排队时返回。
• npx @insforge/cli projects upgrade-instance <type> [--project <id>] - 更改实例类别。有效值：nano、micro、small、medium、large、xl（xl 是上限）。重启项目并更改账单。
• npx @insforge/cli projects delete --project <id> - 永久删除项目及其所有资源。--project 是必需的（不会默认为链接项目）。不可逆——首先与用户确认确切的项目 ID；这是一个受保护的人工参与操作，因此不要自动绕过确认。
• npx @insforge/cli projects transfer <targetOrgId> --project <id> - 将项目转移到另一个组织（账单和访问权限随之转移）。--project 是必需的（不会默认为链接项目）。受保护，人工参与——首先确认源项目和目标组织。

配置：

• 使用 npx @insforge/cli config export、config plan 和 config apply 处理支持的 insforge.toml 设置。
• TOML 仅用于配置值。SQL 属于 db migrations；函数代码属于 functions deploy；前端代码属于 deployments deploy；计算代码/镜像属于 compute deploy。
• 如果 config apply 返回 skipped[]，报告跳过的项和所需的后端升级。不要使用原始 HTTP 重试。

组织和成员

组织范围命令按以下顺序解析组织：--org-id 标志、INSFORGE_ORG_ID、链接项目的组织、配置的默认组织，然后提示（或单个组织自动选择）。传递 --org-id <id> 以对特定组织操作。

• npx @insforge/cli orgs list - 列出你所属的组织。
• npx @insforge/cli orgs create <name> [--type personal|team|company] - 创建组织（默认类型 team）。
• npx @insforge/cli orgs update [--name <name>] [--type <type>] [--org-id <id>] - 重命名或更改组织类型。
• npx @insforge/cli orgs members list [--org-id <id>] - 列出成员和待处理的邀请。
• npx @insforge/cli orgs members invite <email> [--role administrator|developer] [--org-id <id>] - 邀请成员（默认角色 developer）。
• npx @insforge/cli orgs members role <memberId> <role> [--org-id <id>] - 更改成员角色（administrator 或 developer）。
• npx @insforge/cli orgs members remove <memberId> [--org-id <id>] - 移除成员。首先确认意图。

计费和用量

检查组织的计划/消费并管理其订阅。组织解析与组织部分匹配。

• npx @insforge/cli billing status [--org-id <id>] - 显示当前订阅/计划和周期。
• npx @insforge/cli billing credits [--org-id <id>] - 显示信用余额和最近的信用交易。
• npx @insforge/cli billing history [--org-id <id>] - 列出过去的付款/发票。
• npx @insforge/cli billing cycles [--org-id <id>] - 显示当前和上一个计费周期窗口。
• npx @insforge/cli usage [--org-id <id>] - 显示当前计费周期的消费（摘要加上按项目细分：数据库、存储、出口等）。
• npx @insforge/cli billing upgrade <plan> [--org-id <id>] - 启动 Stripe 结账以更改计划（free | starter | pro | team | enterprise）。在浏览器中打开托管的结账 URL 并打印它。使用 --json 时，打印 JSON 对象（{ checkoutUrl, sessionId }）且不打开浏览器——在无头/CI 中使用此模式。在用户完成结账前不会收费；后端验证计划和管理员权限。
• npx @insforge/cli billing manage [--org-id <id>] - 打开 Stripe 客户门户以管理订阅、付款方式或取消。在浏览器中打开门户 URL 并打印它。使用 --json 时，打印 JSON 对象（{ portalUrl }）且不打开浏览器——在无头/CI 中使用此模式。

备份

除非给出 --project <id>，否则对链接项目操作。

• npx @insforge/cli backups list [--project <id>] - 列出备份。
• npx @insforge/cli backups latest [--project <id>] - 显示最近的备份。
• npx @insforge/cli backups create [--name <name>] [--wait] [--project <id>] - 创建备份。--name 是可选的；提供时长度必须为 1-64 个字符。--wait 阻塞直到完成，而不是在排队时返回。
• npx @insforge/cli backups rename <backupId> <name> [--project <id>] - 重命名备份（传递 "" 以清除名称）。
• npx @insforge/cli backups delete <backupId> [--project <id>] - 删除备份。首先确认意图。
• npx @insforge/cli backups restore <backupId> [--project <id>] - 从备份恢复项目。这会覆盖项目的当前数据库和存储；自该备份以来写入的数据将丢失。首先确认意图。

存储

• npx @insforge/cli storage buckets - 列出存储桶。
• npx @insforge/cli storage create-bucket <name> [--private] - 创建存储桶。
• npx @insforge/cli storage delete-bucket <name> - 删除存储桶及其所有对象。首先确认破坏性意图。
• npx @insforge/cli storage list-objects <bucket> [--prefix] [--search] [--limit] [--sort] - 检查对象。
• npx @insforge/cli storage upload <file> --bucket <name> [--key <objectKey>] - 上传对象。
• npx @insforge/cli storage download <objectKey> --bucket <name> [--output <path>] - 下载对象。
• npx @insforge/cli storage s3-keys list - 列出 S3 兼容的访问密钥（从不显示密钥值）。
• npx @insforge/cli storage s3-keys create [--description <text>] - 创建 S3 访问密钥。秘密访问密钥在创建时仅显示一次——立即捕获它。
• npx @insforge/cli storage s3-keys delete <id> - 删除 S3 访问密钥。使用它的工具将停止工作。首先确认意图。

对于通过 Postgres 策略实现的存储访问控制行为，请使用存储特定的产品文档或功能指南。不要将存储内部视为通用的公共模式数据库表，除非引用的存储文档明确说明。

实时

通过迁移创建频道模式、应用表发布触发器和频道/消息 RLS。参见 references/realtime.md。

边缘函数

• npx @insforge/cli functions list - 列出已部署的函数。
• npx @insforge/cli functions code <slug> - 查看函数源代码。
• npx @insforge/cli functions deploy <slug> --file <path> - 部署或更新。参见 references/functions-deploy.md。
• npx @insforge/cli functions invoke <slug> [--data <json>] [--method GET|POST] - 调用函数。
• npx @insforge/cli functions delete <slug> - 删除函数。首先确认破坏性意图。

AI 网关

• npx @insforge/cli ai setup 获取链接项目的活动 OpenRouter 密钥，并将 OPENROUTER_API_KEY 写入本地服务器端环境文件。
• 将 OPENROUTER_API_KEY 仅限服务器使用。切勿将其暴露为 NEXT_PUBLIC_*、VITE_*、PUBLIC_* 或 REACT_APP_*。

记忆

每个项目都有内置的代理记忆：持久的事实、决策和陷阱，跨会话保留。将其作为本能反应，而不是事后想法。

• npx @insforge/cli memory list - 廉价的标题索引（无 AI 调用）。在非平凡任务开始时运行；回忆与任务相关的任何标题。
• npx @insforge/cli memory recall "<query>" [--scope] [--limit] [--threshold] - 语义+关键词回忆。
• npx @insforge/cli memory remember "<content>" [--kind] [--title] [--scope] [--source] - 存储一条原子记忆。在决策和陷阱发生时立即记录，而不是在会话结束时。
• npx @insforge/cli memory remember --file <path> - 从转录或笔记文件中提取持久记忆。

存储是幂等的：重新记住已知事实是无操作的，矛盾的事实会更新现有记忆而不是重复——当真相改变时，只需 remember 新真相。参见 references/memory.md 了解存储内容、种类和示例。

支付

使用 payments 进行 Stripe/Razorpay 后端设置和目录同步。参见 references/payments/overview.md。

• 支付是特定于提供商的：显式使用 payments stripe ... 或 payments razorpay ...。
• 使用 payments <provider> config set 配置提供商密钥；设置密钥会在密钥或账户更改时自动同步提供商状态。
• 使用 payments <provider> status 检查密钥/账户/同步/Webhook 健康状态。
• 运行 payments <provider> sync 手动刷新或重试镜像的提供商数据。
• Stripe 使用产品/价格并支持托管 Webhook 注册；Razorpay 使用项目/计划/订单，需要在 Razorpay 仪表板中手动设置 Webhook。
• 构建时优先使用测试模式。仅在用户明确批准后使用生产模式。
• 如果后端报告支付不可用，请要求用户/管理员启用或升级支付。不要通过将提供商密钥存储为通用密钥或将支付密钥嵌入应用代码来绕过。
• 在提供商特定设置前加载 references/payments/stripe.md 或 references/payments/razorpay.md。

运行时结账、订阅、客户门户流程和应用代码属于 insforge 应用集成技能。

部署

前端部署：

• 当应用有构建步骤时，先本地构建。
• 确保前端运行时环境变量在部署前配置了正确的框架前缀。
• 对前端源目录使用 npx @insforge/cli deployments deploy <dir>。不要部署生成的输出目录，除非部署参考明确要求。
• 参见 references/deployments/deploy.md。

自定义域名：

• 使用 npx @insforge/cli domains ... 处理自定义域名、Cloudflare Registrar、DNS 同步和 SSL 验证。
• 参见 references/deployments/domains.md。

后端计算服务：

• 使用 npx @insforge/cli compute ...；不要直接使用用户自己的 flyctl 账户管理 InsForge 计算服务。
• 对包含 Dockerfile 的目录使用源模式，或对预构建镜像使用 --image <url> 的图像模式。
• 使用 --env-file 或可重复的 env-set/update 命令处理密钥，而不是大型内联 JSON。
• 参见 references/compute-deploy.md。

密钥

• npx @insforge/cli secrets list [--all] - 列出密钥名称而不显示值。
• npx @insforge/cli secrets get <key> - 仅在必要时检索密钥值。
• npx @insforge/cli secrets add <key> <value> [--reserved] [--expires <ISO date>] - 创建密钥。
• npx @insforge/cli secrets update <key> [--value] [--active] [--reserved] [--expires] - 更新密钥。
• npx @insforge/cli secrets delete <key> - 软删除密钥。首先确认意图。
• npx @insforge/cli secrets rotate <api-key|anon-key> [--grace-hours <n>] - 轮换项目 API 密钥或匿名密钥。新密钥仅打印一次——捕获它。旧密钥在宽限期内继续工作（如果省略 --grace-hours，则使用服务器默认值）；在其过期前更新所有消费者。

调度

• npx @insforge/cli schedules list/get/create/update/delete/logs。
• 对于挂钟调度，使用标准 5 字段 cron。
• 对于亚分钟节奏，使用 pg_cron 间隔语法，如 30 seconds。不支持带秒的六字段 cron。
• 标头可以引用 InsForge 密钥，格式为 ${{secrets.KEY_NAME}}。
• 参见 references/schedules.md 了解 cron 格式、密钥标头引用、示例、常见错误和推荐设置工作流。

分支

使用后端分支在应用到生产之前测试有风险的模式、RLS、认证或函数更改。参见 references/branch/overview.md。

常用命令：

• npx @insforge/cli branch create <name> [--mode full|schema-only] [--no-switch]
• npx @insforge/cli branch list
• npx @insforge/cli branch switch <name> 或 --parent
• npx @insforge/cli branch merge <name> [--dry-run] [--save-sql <path>]
• npx @insforge/cli branch reset <name>
• npx @insforge/cli branch delete <name>

分支需要支持它的后端版本。如果不可用，报告后端版本限制，而不是发明变通方法。

诊断和日志

• npx @insforge/cli diagnose - 完整健康报告。
• npx @insforge/cli diagnose --ai "<issue description>" - 要求 InsForge 调试代理诊断具体的后端问题。
• npx @insforge/cli diagnose metrics [--range 1h|6h|24h|7d] - EC2 指标。
• npx @insforge/cli diagnose advisor [--severity critical|warning|info] [--category security|performance|health] - 顾问问题。
• npx @insforge/cli diagnose db [--check <checks>] - 数据库健康检查。
• npx @insforge/cli diagnose logs [--source <name>] [--limit <n>] - 聚合错误日志。
• npx @insforge/cli logs <source> [--limit <n>] - 特定源的后端日志。

典型的日志源包括 function.logs、function-deploy.logs、postgres.logs、postgrest.logs 和 insforge.logs。参见 references/diagnostics.md 了解常见调试场景和源选择。

文档

• npx @insforge/cli docs - 列出文档主题。
• npx @insforge/cli docs instructions - 设置指南。
• npx @insforge/cli docs <feature> <language> - 针对 db、storage、functions、auth、ai 或 realtime 的功能文档，语言为 typescript、swift、kotlin 或 rest-api。

对于使用 InsForge 或 @insforge/sdk 的应用代码，请使用 insforge 应用集成技能，并仅将 docs 作为官方功能参考。

PostHog

• npx @insforge/cli posthog setup 确保仪表板具有 PostHog 连接，然后打印官方 PostHog 向导命令以及连接项目的公共 phc_ API 密钥和主机。
• ⚠️ posthog setup 本身不会检测应用：在向导步骤发生之前，没有环境变量、没有 SDK、没有事件。向导是交互式的，可能会打开浏览器；要求用户在真实终端中运行它，或使用打印的 phc_ 密钥/主机手动检测（PostHog 的公共客户端密钥，在前端环境变量中安全）。
• 仅限云：自托管后端不暴露集成。不要将来自单独 PostHog 账户的 phc_ 密钥替换到应用环境变量中——分析页面读取的是仅由 posthog setup 填充的服务器端连接；使用它打印的密钥。

Apify 网页抓取器

• npx @insforge/cli webscraper apify connect — 一次性 OAuth 连接；在 InsForge 中存储可刷新的令牌。
• npx @insforge/cli webscraper apify login — 认证桥接：获取 InsForge 管理的令牌，运行 apify login --token，并安装 Apify 的官方代理技能。切勿运行普通的 apify login（浏览器 OAuth）。在任何 Apify 401 / "未登录" 时，重新运行 login。
• 参见 references/webscraper/apify.md 了解完整的抓取→落地→调度工作流和基于大小的落地策略。

非交互式 CI/CD

在自动化上下文中使用环境变量和 JSON 模式：

INSFORGE_EMAIL=$EMAIL INSFORGE_PASSWORD=$PASSWORD npx @insforge/cli login --email -y
npx @insforge/cli link --project-id $PROJECT_ID --org-id $ORG_ID -y
npx @insforge/cli db query "SELECT 1 AS ok" --json

项目配置文件

在 create 或 link 之后，.insforge/project.json 包含链接的项目 ID、应用密钥、区域、API 密钥和后端 URL。

• 切勿提交 .insforge/project.json 或公开分享它。
• 不要手动编辑它。使用 npx @insforge/cli link 或分支命令切换项目。