copilotkit-cli

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

CopilotKit CLI

CopilotKit CLI

bash
npx copilotkit@latest <command>
--help
on any command prints its flags. The commands below are the ones worth knowing before you start reading someone's project by hand.
bash
npx copilotkit@latest <command>
任意命令加上
--help
可打印其参数标志。在你开始手动排查他人项目之前,以下是值得了解的命令。

verify
— do this before debugging

verify
—— 调试前先执行此命令

bash
npx copilotkit@latest verify --json
One 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
checks[]
rather than assuming a fixed set. With
--expect-runtime oss
the hosted-project and credential checks do not apply at all, so that run is a smaller set.
Crucially it names which URL it probed and where that URL came from — the project's
runtimeUrl
, 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.
Useful flags:
  • --frontend-url <origin you actually open>
    — adds the browser-facing checks, including a real CORS preflight when that origin differs from the runtime's
  • --round-trip
    — also runs the agent and reads its answer back. Costs a model call, so it is opt-in
  • --expect-runtime oss
    — for a self-hosted runtime with no Intelligence. It exits zero only when
    /info
    declares the named agent, reports no Intelligence entitlement, and
    --round-trip --agent <id>
    passes
  • --agent <id>
    — which declared agent to run, when several are registered
  • --runtime-url <url>
    — probe this endpoint instead of the one read from the project
  • --header '<name>: <value>'
    — repeatable. Needed when the project's
    identifyUser
    reads a session the CLI does not carry
  • --timeout <seconds>
    — how long to wait for an answer, default 90
Read
checks[]
and fix in the order given:
  • 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.
  • UNKNOWN
    means the check could not run. It never means the check passed, and the command exits non-zero unless every check passed.
bash
npx copilotkit@latest verify --json
这一条命令可替代手动排查,最多可检查11项内容:已选中托管项目;项目API密钥存在、可被应用加载且能通过认证;runtime正常响应、声明了agent、实际使用了凭证,并且提供对话线程路由;前端可正常提供自身静态资源;runtime接受浏览器的源地址;已安装的CopilotKit包版本与runtime上报的版本一致。它还会上报runtime版本、使用的agent框架、转录功能是否已配置、实时网关配置情况以及许可证状态。
11项是上限,而非固定检查项。如果没有可对照的检查对象(例如未找到前端源地址,或未安装相关包),最后三项会被省略。请以
checks[]
数组的实际内容为准,不要假设是固定的检查集合。使用
--expect-runtime oss
参数时,托管项目和凭证相关的检查完全不适用,因此运行时的检查项会更少。
至关重要的是,它会明确说明探测的是哪个URL,以及该URL的来源——是项目的
runtimeUrl
、环境变量、应用自身的开发配置,还是假设的默认值。手动排查无法告诉你这些信息,而来源会影响判定结果:如果项目指定的URL没有响应,判定为FAIL(失败);而假设的默认URL没有响应,则判定为UNKNOWN(未知),因为运行在命令未获知的端口上的应用不属于连通配置故障。
常用参数:
  • --frontend-url <你实际打开的源地址>
    —— 添加面向浏览器的检查,包括当该源地址与runtime不同时执行真实的CORS预检请求
  • --round-trip
    —— 同时运行agent并读取其返回结果。会消耗一次模型调用,因此是可选开启的功能
  • --expect-runtime oss
    —— 用于无Intelligence服务的自托管runtime。仅当
    /info
    接口声明了指定的agent、上报无Intelligence权限,且
    --round-trip --agent <id>
    通过时,命令才会以0状态码退出
  • --agent <id>
    —— 当注册了多个agent时,指定要运行的已声明agent
  • --runtime-url <url>
    —— 探测此端点,而非从项目中读取的端点
  • --header '<名称>: <值>'
    —— 可重复使用。当项目的
    identifyUser
    需要读取CLI未携带的会话时,需要使用此参数
  • --timeout <秒数>
    —— 等待响应的时长,默认90秒
请按照
checks[]
数组给出的顺序依次修复:
  • 检查项是链式关联的。如果后续检查项无法运行,会明确说明并指出需要先修复的前置检查项,因此第一个失败项就是根本问题所在。
  • UNKNOWN
    表示该检查无法运行,绝不代表检查通过。除非所有检查都通过,否则命令会以非零状态码退出。

What
verify
does not cover

verify
不涵盖的内容

Reach past it only once it is clean.
  • Tool execution.
    --round-trip
    deliberately asks a question that needs no tools and sends no context, so a passing round trip says nothing about whether your tools work.
  • 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 it
Prompts 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
onboard start
below.
To add CopilotKit to an existing app, either follow the quickstart, or hand the job to your coding agent:
bash
npx copilotkit@latest onboard start
That runs an agent-guided flow over the repository you are already in, with checkpoints and proof steps rather than a scaffold.
onboard start --intent <feature>
targets one feature on an app that already has CopilotKit.
bash
npx copilotkit@latest init          # `create` is an alias for it
该命令会提示输入项目名称和框架,搭建启动模板,在需要时让你登录,并将应用连接到云托管的Intelligence项目。它要求输入的名称会作为新目录的名称,因此适用于尚未创建的项目。对于已有的应用,请使用下方的
onboard start
命令。
要将CopilotKit添加到现有应用中,你可以遵循快速开始指南,也可以将这项工作交给你的编码Agent:
bash
npx copilotkit@latest onboard start
该命令会在你当前所在的代码仓库中运行Agent引导的接入流程,包含检查点和验证步骤,而非直接生成脚手架模板。
onboard start --intent <功能>
可用于为已集成CopilotKit的应用添加指定功能。

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 --json
Use
login --json
when you are driving the CLI. Bare
login
tries to open a browser, which is not something you can complete.
There is no
auth
command. It is
login
.
project select
records the choice in
.copilotkit/project.json
and provisions a project-scoped runtime key into
.env
:
CPK_INTELLIGENCE_API_KEY=cpk_...
CPK_INTELLIGENCE_API_KEY
is the canonical name and the only one the CLI writes. Keep it server-side — it is a runtime key, not a frontend token, so it takes no
NEXT_PUBLIC_
or
VITE_
prefix. Do not set the platform URLs: they default to the managed hosts, so any value you supply can only replace a correct default with a worse one.
Without a TTY — which is what a coding agent has — use
project list --json
to see the choices and
project select --project <id>
or
--create <name>
to name the answer up front.
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 --json
。直接使用
login
会尝试打开浏览器,这种方式无法在非交互环境下完成。
没有
auth
命令,登录命令是
login
。
project select
会将选择记录到
.copilotkit/project.json
中,并将项目级别的runtime密钥写入
.env
文件:
CPK_INTELLIGENCE_API_KEY=cpk_...
CPK_INTELLIGENCE_API_KEY
是标准名称,也是CLI唯一会写入的密钥变量。请将其保存在服务端——这是runtime密钥,而非前端令牌,因此不要添加
NEXT_PUBLIC_
或
VITE_
前缀。不要自行设置平台URL:它们默认指向托管服务,你提供的任何值都只会把正确的默认值替换成错误的。
在无TTY的环境下(例如编码Agent运行的环境),请使用
project list --json
查看可选项目,然后通过
project select --project <id>
或
--create <名称>
直接指定结果。

Other commands

其他命令

CommandWhat it does
skills install
Installs these skills into a project (
skills onboard
also starts onboarding)
typegen
Generates type-safe agent ids from a running runtime
import --source adk|langgraph --dry-run
Previews importing historical threads into Intelligence
license create
/
license list
Issues and lists license tokens
channels
Sets up managed Intelligence Channels for Slack or Microsoft Teams
framework list
The agent frameworks
create
accepts, and their flags
logs
The CLI log path, or recent lines
telemetry
Shows or changes the CLI telemetry preference
docs
Opens the documentation
version
Version, build, and commit
The CLI collects usage data.
DO_NOT_TRACK=1
or
COPILOTKIT_TELEMETRY_DISABLED=1
opts out.
命令功能说明
skills install
将这些skills安装到项目中(
skills onboard
也会启动接入流程)
typegen
从运行中的runtime生成类型安全的agent ID
import --source adk|langgraph --dry-run
预览将历史对话线程导入Intelligence的效果
license create
/
license list
签发并列出许可证令牌
channels
为Slack或Microsoft Teams配置托管的Intelligence Channels
framework list
列出
create
命令支持的agent框架及其参数
logs
查看CLI日志路径或最近的日志内容
telemetry
查看或修改CLI遥测数据偏好设置
docs
打开文档
version
查看版本、构建信息和提交记录
该CLI会收集使用数据。设置
DO_NOT_TRACK=1
或
COPILOTKIT_TELEMETRY_DISABLED=1
可退出数据收集。