inngest-api-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Inngest API CLI

Use this skill when the task is operational: inspect, debug, sync, invoke, or query Inngest API resources through the terminal. This skill is intentionally prescriptive so agents can act without guessing.

For general CLI setup,

inngest dev

, Docker, local testing, MCP setup, or self-hosted

inngest start

, use

inngest-cli

. For code changes, pair this with the domain skill that owns the code pattern:

inngest-setup

inngest-durable-functions

inngest-events

inngest-steps

inngest-flow-control

inngest-realtime

, or

inngest-middleware

当任务为通过终端检查、调试、同步、调用或查询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

。

First Move

第一步操作

Verify the current CLI surface before relying on memory:

bash

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

The active API command is

inngest api

. If prompt context or old docs mention

inngest alpha api

, switch to

inngest api

Use

inngest-api

only when:

The CLI does not expose the needed endpoint.
The user explicitly asks for raw REST API v2.
You need the OpenAPI spec or LLM API docs to resolve request shape.

For complete command flags, read references/cli-commands.md after this skill triggers.

在依赖记忆之前，先验证当前CLI的可用命令：

bash

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。

Target Rules

目标规则

Local is the default target for
```
inngest api
```
.
Cloud Production requires
```
--prod
```
.
Non-production Cloud environments require
```
INNGEST_ENV=<name>
```
or
```
--env
```
.
Prefer
```
INNGEST_API_KEY
```
for Cloud API access.
Do not pass API keys inline with
```
--api-key <secret>
```
unless the user explicitly accepts process-list and transcript exposure.
Never write API keys, event keys, signing keys, webhook URLs, or decrypted secrets into source files, docs, fixtures, or final answers.

Common targets:

bash

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

```
inngest api
```
默认目标为本地环境。
云生产环境需要添加
```
--prod
```
参数。
非生产云环境需要设置
```
INNGEST_ENV=<name>
```
或添加
```
--env
```
参数。
优先使用
```
INNGEST_API_KEY
```
进行云API访问。
除非用户明确接受进程列表和记录暴露，否则不要通过
```
--api-key <secret>
```
直接传入API密钥。
切勿将API密钥、事件密钥、签名密钥、Webhook URL或解密后的机密信息写入源文件、文档、测试数据或最终答案中。

常见目标示例：

bash

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

Local Development

本地开发

For local app work:

Start the user's app with local dev mode when applicable, for example
```
INNGEST_DEV=1 npm run dev
```
.
Start the dev server:
bash
```
npx inngest-cli@latest dev
```
Prefer Dev Server MCP tools, when available, to list local functions, send test events, inspect runs, and watch status.
Use
```
npx inngest-cli@latest api ...
```
for API-compatible local checks, command-help verification, and workflows not exposed through MCP.

If the local API says the dev server is unavailable, start

inngest dev

or switch to Cloud with

--prod

when the user is debugging deployed runs.

针对本地应用工作：

若适用，启动用户应用的本地开发模式，例如
```
INNGEST_DEV=1 npm run dev
```
。
启动开发服务器：
bash
```
npx inngest-cli@latest dev
```
若可用，优先使用开发服务器MCP工具来列出本地函数、发送测试事件、检查运行状态并监控状态。
使用
```
npx inngest-cli@latest api ...
```
进行兼容API的本地检查、命令帮助验证以及MCP未暴露的工作流。

如果本地API提示开发服务器不可用，请启动

inngest dev

，或者当用户调试已部署的运行时切换到云环境并添加

--prod

参数。

Command Routing

命令路由

Use this table before asking the human for more context.

Situation	Command path
Check CLI/API reachability	`api health`
Confirm Cloud auth	`api --prod get-account`
List environments	`api --prod get-account-envs --limit 10`
List event keys	`api --prod get-account-event-keys --limit 10`
List signing keys	`api --prod get-account-signing-keys --limit 10`
List webhooks	`api --prod get-webhooks`
User gives a run ID	`api --prod get-function-run <run_id>`
Need step-level detail	`api --prod get-function-trace <run_id> --include-output`
User gives an event ID	`api --prod get-event-runs <event_id> --limit 5 --include-output`
Sync a known app ID	`api --prod sync-app --app-id <app_id> --url <serve_url>`
Invoke a known app/function ID	`api --prod invoke-function --app-id <app_id> --function-id <function_id> --data '<json>'`
Discover Insights tables	`api --prod get-insights-tables`
Discover event schemas for Insights	`api --prod get-insights-event-schemas --limit 25`
Draft an Insights query	`api --prod query-insights-prompt --prompt '<request>'`
Run an Insights query	`api --prod query-insights --query '<sql>'`

If a command accepts positional IDs, prefer positional IDs in examples because they are shorter and match current help. Flag forms such as

--run-id

are also accepted by the current CLI for many path parameters.

在向用户询问更多上下文之前，请使用下表。

场景	命令路径
检查CLI/API可达性	`api health`
确认云环境认证	`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的事件 schema	`api --prod get-insights-event-schemas --limit 25`
编写Insights查询	`api --prod query-insights-prompt --prompt '<request>'`
运行Insights查询	`api --prod query-insights --query '<sql>'`

如果命令接受位置参数形式的ID，示例中优先使用位置参数，因为它们更简洁且与当前帮助文档一致。当前CLI也接受许多路径参数的标志形式，例如

--run-id

。

Debug a Run

调试运行

When the user gives a run ID:

bash

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

Summarize status, failed spans, retry state, timing, error names/messages, and the likely code boundary to inspect. Do not paste full traces unless asked.

When the user gives an event ID:

bash

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

Pick the relevant run from the response, then fetch the run and trace. If multiple runs are plausible, explain the candidates and use timestamps, function IDs, or failure status to choose.

当用户提供运行ID时：

bash

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时：

bash

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

从响应中选择相关的运行，然后获取该运行和追踪信息。如果有多个合理的运行候选，请说明候选内容并使用时间戳、函数ID或失败状态进行选择。

Missing IDs

缺失ID

Do not immediately ask the user for app IDs, function IDs, or run IDs.

Try, in order:

Dev Server MCP tools, if available.
The user's prompt, pasted dashboard URLs, logs, alert text, or stack traces.
Repository config and Inngest serve definitions.
Event ID lookup with
```
get-event-runs
```
.
Current CLI help to see if discovery commands such as
```
get-functions
```
or
```
get-app
```
have appeared.

Ask the user for the ID only after those sources cannot provide it.

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

请按以下顺序尝试获取：

若可用，使用开发服务器MCP工具。
用户的提示、粘贴的仪表板URL、日志、警报文本或堆栈跟踪。
仓库配置和Inngest服务定义。
使用
```
get-event-runs
```
查询事件ID。
当前CLI帮助文档，查看是否出现了
```
get-functions
```
或
```
get-app
```
等发现命令。

仅当以上来源无法提供ID时，才向用户索要。

Mutating Operations

变更操作

Read before write. List or fetch the relevant resource first, then mutate only when target and intent are clear.

Confirm before running these against Cloud unless the user already specified the account/environment and exact intent:

```
create-env
```
```
patch-env
```
```
create-webhook
```
```
sync-app
```
```
invoke-function
```
Broad or expensive
```
query-insights
```
calls

For repeatable invocation tests, use a stable idempotency key:

bash

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

For complex JSON, use

--body-file

to avoid quoting mistakes.

先读后写。先列出或获取相关资源，仅当目标和意图明确时才执行变更操作。

除非用户已指定账户/环境和确切意图，否则在针对云环境运行以下命令前请确认：

```
create-env
```
```
patch-env
```
```
create-webhook
```
```
sync-app
```
```
invoke-function
```
范围广泛或开销较大的
```
query-insights
```
调用

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

bash

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

Use Insights when the question is analytic, when logs only give partial clues, or when the user asks about trends, frequency, volume, failures over time, or event/run data.

Start small:

bash

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"

Inspect generated SQL before running broad queries. Add limits and time windows when possible.

当问题为分析类、日志仅提供部分线索，或用户询问趋势、频率、数量、一段时间内的失败情况，或事件/运行数据时，使用Insights。

从小规模查询开始：

bash

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。尽可能添加限制条件和时间窗口。

Output Handling

输出处理

CLI output is JSON. Parse it structurally before making decisions.
Use
```
--raw
```
only when a downstream command needs exact response bodies.
If responses are paginated and
```
page.hasMore
```
is true, continue with
```
--cursor
```
when complete results are needed.
Treat missing
```
data
```
on list responses as an empty list unless an error is present.
Redact secrets, webhook URLs, token values, and sensitive payload fields in summaries.

CLI输出为JSON格式。在做出决策前先结构化解析输出。
仅当下游命令需要确切响应体时才使用
```
--raw
```
参数。
如果响应是分页的且
```
page.hasMore
```
为true，当需要完整结果时请使用
```
--cursor
```
继续查询。
除非存在错误，否则将列表响应中缺失的
```
data
```
视为空列表。
在总结中编辑机密信息、Webhook URL、令牌值和敏感负载字段。

Drift Handling

版本差异处理

The CLI is beta. If behavior differs from this skill:

Run top-level and command-specific help.
Check
```
https://api-docs.inngest.com/llms.txt
```
.

Check

https://api-docs.inngest.com/api-specs/v2.json

Use the
```
inngest-api
```
skill for raw REST API fallback.

Some launch material may mention aliases such as

get-run

invoke-function-by-slug

. Use them only if current

api --help

exposes them. If absent, use

get-function-run

and

invoke-function

CLI处于测试阶段。如果行为与本技能描述不符：

运行顶层和特定命令的帮助文档。
查看
```
https://api-docs.inngest.com/llms.txt
```
。

查看

https://api-docs.inngest.com/api-specs/v2.json

。

使用
```
inngest-api
```
技能进行原始REST API回退。

一些发布材料可能提到

get-run

或

invoke-function-by-slug

等别名。仅当当前

api --help

显示这些别名时才使用它们。如果不存在，请使用

get-function-run

和

invoke-function

。