inngest-api-cli

Inngest API CLI

对于使用已连接 MCP 工具的 Cloud 操作，请优先使用 inngest-cloud。 仅在需要显式执行终端/HTTP 操作，或 MCP 缺少相应功能时，使用此技能。如果 OAuth MCP 可以完成任务，请勿询问 API 密钥。

当任务属于运维操作时，使用此技能：通过终端检查、调试、同步、调用或查询 Inngest API 资源。此技能有意采用规范性指引，让 Agent 无需猜测即可执行操作。

对于常规 CLI 设置、inngest dev、Docker、本地测试、MCP 设置或可自托管的 inngest start，请使用 inngest-cli。对于代码更改，请搭配负责相应代码模式的领域技能：inngest-setup、inngest-durable-functions、inngest-events、inngest-steps、inngest-flow-control、inngest-realtime 或 inngest-middleware。

首要步骤

依赖记忆前，先确认当前 CLI 支持的命令：

npx inngest-cli@latest api --help
npx inngest-cli@latest api <command> --help

当前的 API 命令是 inngest api。如果提示词上下文或旧文档提到 inngest alpha api，请改用 inngest api。

仅在以下情况使用 inngest-api：

• CLI 未提供所需的端点。
• 用户明确要求使用原始 REST API v2。
• 需要 OpenAPI 规范或 LLM API 文档来确定请求格式。

触发此技能后，如需查看完整的命令标志，请阅读 references/cli-commands.md。

目标规则

• inngest api 默认使用本地目标。
• Cloud Production 需要 --prod。
• 非生产环境的 Cloud 环境需要 INNGEST_ENV=<name> 或 --env。
• 访问 Cloud API 时，优先使用 INNGEST_API_KEY。
• 除非用户明确接受进程列表和会话记录泄露密钥的风险，否则不要使用 --api-key <secret> 内联传递 API 密钥。
• 切勿将 API 密钥、事件密钥、签名密钥、Webhook URL 或解密后的密钥写入源文件、文档、测试固件或最终答复。

常见目标：

npx inngest-cli@latest api health
npx inngest-cli@latest api --prod get-account
INNGEST_ENV=staging npx inngest-cli@latest api --prod get-webhooks
npx inngest-cli@latest api --api-host http://127.0.0.1 --api-port 8288 health

本地开发

对于本地应用开发：

1. 在适用时，使用本地开发模式启动用户的应用，例如 INNGEST_DEV=1 npm run dev。

2. 启动开发服务器：

   npx inngest-cli@latest dev
   

3. 如有可用的 Dev Server MCP 工具，优先使用这些工具来列出本地函数、发送测试事件、检查运行情况和监控状态。

4. 使用 npx inngest-cli@latest api ... 执行兼容 API 的本地检查、验证命令帮助信息，以及处理 MCP 未提供的工作流。

如果本地 API 提示开发服务器不可用，请启动 inngest dev；如果用户正在调试已部署的运行，则使用 --prod 切换到 Cloud。

命令路由

在向用户询问更多背景之前，请先使用此表。

情况	命令路径
检查 CLI/API 的连通性	api health
确认 Cloud 身份验证	api --prod get-account
列出环境	api --prod get-account-envs --limit 10
列出事件密钥	api --prod get-account-event-keys --limit 10
列出签名密钥	api --prod get-account-signing-keys --limit 10
列出 Webhook	api --prod get-webhooks
用户提供运行 ID	api --prod get-function-run <run_id>
需要步骤级详细信息	api --prod get-function-trace <run_id> --include-output
用户提供事件 ID	api --prod get-event-runs <event_id> --limit 5 --include-output
同步已知应用 ID	api --prod sync-app --app-id <app_id> --url <serve_url>
调用已知应用/函数 ID	api --prod invoke-function --app-id <app_id> --function-id <function_id> --data '<json>'
发现 Insights 表	api --prod get-insights-tables
发现 Insights 的事件架构	api --prod get-insights-event-schemas --limit 25
起草 Insights 查询	api --prod query-insights-prompt --prompt '<request>'
运行 Insights 查询	api --prod query-insights --query '<sql>'

如果命令接受位置 ID，示例中优先使用位置 ID，因为这样更简洁，也符合当前帮助信息。对于许多路径参数，当前 CLI 也接受 --run-id 等标志形式。

调试一次运行

当用户提供运行 ID 时：

npx inngest-cli@latest api --prod get-function-run <run_id>
npx inngest-cli@latest api --prod get-function-trace <run_id> --include-output

总结状态、失败的跨度、重试状态、耗时、错误名称/消息，以及可能需要检查的代码边界。除非用户要求，否则不要粘贴完整跟踪记录。

当用户提供事件 ID 时：

npx inngest-cli@latest api --prod get-event-runs <event_id> --limit 5 --include-output

从响应中选出相关运行，然后获取该运行和跟踪记录。如果可能的运行有多个，请说明候选项，并根据时间戳、函数 ID 或失败状态进行选择。

缺少 ID

不要立即向用户索要应用 ID、函数 ID 或运行 ID。

请按以下顺序尝试：

1. 如果有 Dev Server MCP 工具，请使用。
2. 查看用户的提示、粘贴的仪表板 URL、日志、告警文本或堆栈跟踪。
3. 查看仓库配置和 Inngest 服务定义。
4. 使用 get-event-runs 查询事件 ID。
5. 查看当前 CLI 帮助，确认是否已有 get-functions 或 get-app 等发现命令。

只有在这些来源都无法提供 ID 后，才向用户索要 ID。

会更改状态的操作

先读后写。先列出或获取相关资源，然后仅在目标和意图明确时进行修改。

除非用户已指定账户/环境和确切意图，否则在 Cloud 上运行以下操作前请先确认：

• create-env
• patch-env
• create-webhook
• sync-app
• invoke-function
• 范围广或成本高的 query-insights 调用

对于可重复的调用测试，请使用稳定的幂等键：

npx inngest-cli@latest api --prod invoke-function \
  --app-id <app_id> \
  --function-id <function_id> \
  --idempotency-key <stable_test_key> \
  --data '{"example":true}'

对于复杂 JSON，请使用 --body-file，以避免引号错误。

Insights

当问题涉及分析、日志只提供部分线索，或用户询问趋势、频率、数量、随时间变化的失败情况或事件/运行数据时，请使用 Insights。

从小范围开始：

npx inngest-cli@latest api --prod get-insights-tables
npx inngest-cli@latest api --prod get-insights-event-schemas --limit 25
npx inngest-cli@latest api --prod query-insights-prompt \
  --prompt "Show failed functions in the last 24 hours"

运行范围广的查询前，请检查生成的 SQL。尽可能添加限制条件和时间范围。

输出处理

• CLI 输出为 JSON。做出判断前，请先按结构解析。
• 仅当下游命令需要精确的响应正文时，才使用 --raw。
• 如果响应是分页的，且 page.hasMore 为 true，那么在需要完整结果时，请继续使用 --cursor。
• 如果列表响应中缺少 data，且没有错误，则将其视为空列表。
• 在摘要中隐藏密钥、webhook URL、令牌值和敏感负载字段。

行为差异处理

CLI 仍处于 beta 阶段。如果其行为与此技能不一致：

1. 运行顶层帮助和命令专属帮助。
2. 查看 https://api-docs.inngest.com/llms.txt。
3. 查看 https://api-docs.inngest.com/api-specs/v2.json。
4. 使用 inngest-api 技能作为原始 REST API 的备用方案。

部分发布材料可能会提到 get-run 或 invoke-function-by-slug 等别名。只有当前 api --help 中提供这些别名时才使用。如果没有，请使用 get-function-run 和 invoke-function。