copilotkit-cli
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseCopilotKit CLI
CopilotKit CLI
bash
npx copilotkit@latest <command>--helpbash
npx copilotkit@latest <command>任意命令加上可打印其参数标志。在你开始手动排查他人项目之前,以下是值得了解的命令。
--helpverify
— do this before debugging
verifyverify
—— 调试前先执行此命令
verifybash
npx copilotkit@latest verify --jsonOne command replaces the manual survey. It settles up to eleven things: a hosted project is
selected; the project API key is present, loadable by the app, and authenticates; the runtime
responds, declares an agent, actually consumes the credential, and serves the thread routes;
the frontend serves its own assets; the runtime accepts the browser's origin; and the
installed CopilotKit packages match the version the runtime reports. It also reports the
runtime version, the agent framework in use, whether transcription is wired, the realtime
gateway wiring, and the license state.
Eleven is the ceiling, not a promise. The last three are omitted when there was nothing to
check them against — no frontend origin was found, or no installed packages were. Count
rather than assuming a fixed set. With the hosted-project
and credential checks do not apply at all, so that run is a smaller set.
checks[]--expect-runtime ossCrucially it names which URL it probed and where that URL came from — the project's
, an environment variable, the app's own dev configuration, or an assumed
default. A survey done by hand cannot tell you that, and the provenance changes the verdict:
nothing answering at a URL the project named is a FAIL, while nothing answering at an
assumed default is UNKNOWN, because an app on a port the command never learned is not a
wiring failure.
runtimeUrlUseful flags:
- — adds the browser-facing checks, including a real CORS preflight when that origin differs from the runtime's
--frontend-url <origin you actually open> - — also runs the agent and reads its answer back. Costs a model call, so it is opt-in
--round-trip - — for a self-hosted runtime with no Intelligence. It exits zero only when
--expect-runtime ossdeclares the named agent, reports no Intelligence entitlement, and/infopasses--round-trip --agent <id> - — which declared agent to run, when several are registered
--agent <id> - — probe this endpoint instead of the one read from the project
--runtime-url <url> - — repeatable. Needed when the project's
--header '<name>: <value>'reads a session the CLI does not carryidentifyUser - — how long to wait for an answer, default 90
--timeout <seconds>
Read and fix in the order given:
checks[]- The checks chain. A later check that could not run says so and names the earlier one to fix first, so the first failure is the real one.
- means the check could not run. It never means the check passed, and the command exits non-zero unless every check passed.
UNKNOWN
bash
npx copilotkit@latest verify --json这一条命令可替代手动排查,最多可检查11项内容:已选中托管项目;项目API密钥存在、可被应用加载且能通过认证;runtime正常响应、声明了agent、实际使用了凭证,并且提供对话线程路由;前端可正常提供自身静态资源;runtime接受浏览器的源地址;已安装的CopilotKit包版本与runtime上报的版本一致。它还会上报runtime版本、使用的agent框架、转录功能是否已配置、实时网关配置情况以及许可证状态。
11项是上限,而非固定检查项。如果没有可对照的检查对象(例如未找到前端源地址,或未安装相关包),最后三项会被省略。请以数组的实际内容为准,不要假设是固定的检查集合。使用参数时,托管项目和凭证相关的检查完全不适用,因此运行时的检查项会更少。
checks[]--expect-runtime oss至关重要的是,它会明确说明探测的是哪个URL,以及该URL的来源——是项目的、环境变量、应用自身的开发配置,还是假设的默认值。手动排查无法告诉你这些信息,而来源会影响判定结果:如果项目指定的URL没有响应,判定为FAIL(失败);而假设的默认URL没有响应,则判定为UNKNOWN(未知),因为运行在命令未获知的端口上的应用不属于连通配置故障。
runtimeUrl常用参数:
- —— 添加面向浏览器的检查,包括当该源地址与runtime不同时执行真实的CORS预检请求
--frontend-url <你实际打开的源地址> - —— 同时运行agent并读取其返回结果。会消耗一次模型调用,因此是可选开启的功能
--round-trip - —— 用于无Intelligence服务的自托管runtime。仅当
--expect-runtime oss接口声明了指定的agent、上报无Intelligence权限,且/info通过时,命令才会以0状态码退出--round-trip --agent <id> - —— 当注册了多个agent时,指定要运行的已声明agent
--agent <id> - —— 探测此端点,而非从项目中读取的端点
--runtime-url <url> - —— 可重复使用。当项目的
--header '<名称>: <值>'需要读取CLI未携带的会话时,需要使用此参数identifyUser - —— 等待响应的时长,默认90秒
--timeout <秒数>
请按照数组给出的顺序依次修复:
checks[]- 检查项是链式关联的。如果后续检查项无法运行,会明确说明并指出需要先修复的前置检查项,因此第一个失败项就是根本问题所在。
- 表示该检查无法运行,绝不代表检查通过。除非所有检查都通过,否则命令会以非零状态码退出。
UNKNOWN
What verify
does not cover
verifyverify
不涵盖的内容
verifyReach past it only once it is clean.
- Tool execution. deliberately asks a question that needs no tools and sends no context, so a passing round trip says nothing about whether your tools work.
--round-trip - Event ordering and streaming. It reports pass or fail on a run, not the sequence inside it. A run that starts and never finishes, or stalls mid-stream, is a job for the Inspector.
- State synchronisation. Snapshot-versus-delta divergence is agent behaviour, not wiring.
仅当该命令检查全部通过后,再进行手动排查。
- 工具执行。 会故意提出一个不需要工具且不发送上下文的问题,因此往返测试通过并不代表你的工具能正常工作。
--round-trip - 事件顺序与流式传输。 它只会上报运行的通过/失败结果,不会上报内部的执行顺序。如果运行启动后从未完成,或在流式传输中途停滞,请使用Inspector进行排查。
- 状态同步。 快照与增量之间的差异属于agent行为问题,而非连通配置问题。
Starting a project
启动项目
bash
npx copilotkit@latest init # `create` is an alias for itPrompts for a name and framework, scaffolds a starter, signs you in when needed, and connects
the app to a cloud-hosted Intelligence project. The name it asks for names the new directory,
so this is the path for a project that does not exist yet. For an app you already have, use
below.
onboard startTo add CopilotKit to an existing app, either follow the quickstart, or hand
the job to your coding agent:
bash
npx copilotkit@latest onboard startThat runs an agent-guided flow over the repository you are already in, with checkpoints and
proof steps rather than a scaffold. targets one feature on
an app that already has CopilotKit.
onboard start --intent <feature>bash
npx copilotkit@latest init # `create` is an alias for it该命令会提示输入项目名称和框架,搭建启动模板,在需要时让你登录,并将应用连接到云托管的Intelligence项目。它要求输入的名称会作为新目录的名称,因此适用于尚未创建的项目。对于已有的应用,请使用下方的命令。
onboard start要将CopilotKit添加到现有应用中,你可以遵循快速开始指南,也可以将这项工作交给你的编码Agent:
bash
npx copilotkit@latest onboard start该命令会在你当前所在的代码仓库中运行Agent引导的接入流程,包含检查点和验证步骤,而非直接生成脚手架模板。可用于为已集成CopilotKit的应用添加指定功能。
onboard start --intent <功能>Signing in and picking a project
登录与选择项目
bash
npx copilotkit@latest login --json # agent-readable JSON lines, no browser launch
npx copilotkit@latest login # interactive: opens a browser
npx copilotkit@latest whoami # who is signed in, and the active organization
npx copilotkit@latest project select # pick or create a hosted project for this directory
npx copilotkit@latest project list --jsonUse when you are driving the CLI. Bare tries to open a browser, which
is not something you can complete.
login --jsonloginThere is no command. It is .
authloginproject select.copilotkit/project.json.envCPK_INTELLIGENCE_API_KEY=cpk_...CPK_INTELLIGENCE_API_KEYNEXT_PUBLIC_VITE_Without a TTY — which is what a coding agent has — use to see the
choices and or to name the answer up front.
project list --jsonproject select --project <id>--create <name>bash
npx copilotkit@latest login --json # agent-readable JSON lines, no browser launch
npx copilotkit@latest login # interactive: opens a browser
npx copilotkit@latest whoami # who is signed in, and the active organization
npx copilotkit@latest project select # pick or create a hosted project for this directory
npx copilotkit@latest project list --json当你通过脚本调用CLI时,请使用。直接使用会尝试打开浏览器,这种方式无法在非交互环境下完成。
login --jsonlogin没有命令,登录命令是。
authloginproject select.copilotkit/project.json.envCPK_INTELLIGENCE_API_KEY=cpk_...CPK_INTELLIGENCE_API_KEYNEXT_PUBLIC_VITE_在无TTY的环境下(例如编码Agent运行的环境),请使用查看可选项目,然后通过或直接指定结果。
project list --jsonproject select --project <id>--create <名称>Other commands
其他命令
| Command | What it does |
|---|---|
| Installs these skills into a project ( |
| Generates type-safe agent ids from a running runtime |
| Previews importing historical threads into Intelligence |
| Issues and lists license tokens |
| Sets up managed Intelligence Channels for Slack or Microsoft Teams |
| The agent frameworks |
| The CLI log path, or recent lines |
| Shows or changes the CLI telemetry preference |
| Opens the documentation |
| Version, build, and commit |
The CLI collects usage data. or opts out.
DO_NOT_TRACK=1COPILOTKIT_TELEMETRY_DISABLED=1| 命令 | 功能说明 |
|---|---|
| 将这些skills安装到项目中( |
| 从运行中的runtime生成类型安全的agent ID |
| 预览将历史对话线程导入Intelligence的效果 |
| 签发并列出许可证令牌 |
| 为Slack或Microsoft Teams配置托管的Intelligence Channels |
| 列出 |
| 查看CLI日志路径或最近的日志内容 |
| 查看或修改CLI遥测数据偏好设置 |
| 打开文档 |
| 查看版本、构建信息和提交记录 |
该CLI会收集使用数据。设置或可退出数据收集。
DO_NOT_TRACK=1COPILOTKIT_TELEMETRY_DISABLED=1