copilotkit-cli

CopilotKit CLI

npx copilotkit@latest <command> --via skill:copilotkit-cli

从此技能运行的每条命令都要带上 --via skill:copilotkit-cli。它只会告知 CopilotKit 的遥测系统此次调用来自此技能，命令本身会忽略它。 如果 CLI 报告 Unknown option '--via'，说明 npx 运行的是旧缓存版本：不带此标志重新运行命令。

任何命令都可以通过 --help 打印其标志。开始手动阅读某个项目之前，以下命令值得先了解。

verify — 调试前先运行

先判断应用是否使用托管 Intelligence。默认情况下，verify 会检查这一点，而开源应用每次都会在这些检查中失败。

• 不使用 Intelligence： 构建运行时的位置没有创建 CopilotKitIntelligence，并且不存在 .copilotkit/project.json。运行开源检查，并使用运行时注册的 Agent ID：

  npx copilotkit@latest verify --expect-runtime oss --round-trip --agent <id> --json --via skill:copilotkit-cli
  

  此处必须使用 --round-trip --agent <id>。如果不加，命令不会尝试往返测试，因此无法通过。

• 其他情况： 运行默认检查。

  npx copilotkit@latest verify --json --via skill:copilotkit-cli
  

不要仅仅为了让 verify 通过而运行 login 或 project select。这些命令会配置托管 Intelligence，但无法修复开源应用；之后 verify 仍会失败，因为运行时从未使用该凭据。

一个命令即可取代手动检查。它会确认最多 11 项内容：已选择托管项目；项目 API 密钥存在、应用能够加载并通过身份验证；运行时会响应、声明了 Agent、确实使用该凭据并提供线程路由；前端提供自己的资源；运行时接受浏览器的来源；已安装的 CopilotKit 软件包与运行时报告的版本一致。此外，它还会报告运行时版本、使用的 Agent 框架、是否接入了转录、实时网关接入情况以及许可证状态。

11 项是上限，并非保证一定会检查这么多项。若没有可供检查的对象（例如未找到前端来源或未找到已安装的软件包），则会省略最后三项。请查看 checks[]，不要假定检查项数量固定。使用 --expect-runtime oss 时，托管项目和凭据检查完全不适用，因此该次运行包含的检查项会更少。

重要的是，它会指出探测了哪个 URL，以及该 URL 的来源——项目的 runtimeUrl、环境变量、应用自身的开发配置，或推定的默认值。手动检查无法得知这些信息，而来源会影响判定结果：如果项目指定的 URL 没有响应，则判定为 FAIL；如果推定的默认 URL 没有响应，则判定为 UNKNOWN，因为应用运行在命令无法获知的端口上，并不代表接线故障。

实用标志：

• --frontend-url <实际打开的来源> — 添加面向浏览器的检查；当该来源与运行时来源不同时，还会执行实际的 CORS 预检
• --round-trip — 也会运行 Agent 并读取其回答。需要调用模型，因此默认不启用
• --expect-runtime oss — 用于没有 Intelligence 的可自托管运行时。仅当 /info 声明了指定的 Agent、报告没有 Intelligence 权益，并且 --round-trip --agent <id> 通过时，才会以零退出码退出
• --agent <id> — 注册了多个 Agent 时，指定要运行哪个已声明的 Agent
• --runtime-url <url> — 探测此端点，而不是从项目中读取的端点
• --header '<name>: <value>' — 可重复使用。当项目的 identifyUser 会读取 CLI 未携带的会话时，需要此标志
• --timeout <seconds> — 等待回答的时长，默认值为 90

查看 checks[] 并按列出的顺序修复：

• 检查项会依次关联。无法运行的后续检查会说明原因，并指出要先修复哪一项，因此第一个失败项才是真正的问题。
• UNKNOWN 表示检查无法运行，并不表示检查通过。除非所有检查都通过，否则命令会以非零状态码退出。

verify 不覆盖的内容

只有在它通过之后，才继续往下走。

• 工具执行。 --round-trip 有意提出一个不需要任何工具、也不发送任何上下文的问题，因此往返测试通过并不能说明你的工具是否可用。
• 事件顺序与流式传输。 它只报告某次运行的通过与失败，而不报告其中的顺序。一次开始后永不结束、或中途停滞的运行，是 Inspector 要处理的事。
• 状态同步。 快照与增量的差异属于 agent 行为，而不是接线问题。

启动项目

npx copilotkit@latest init --via skill:copilotkit-cli   # `create` is an alias for it

会提示输入名称和框架，搭建一个起始项目，在需要时为你登录，并将应用连接到一个云端托管的 Intelligence 项目。它询问的名称就是新目录的名称，因此这条路径适用于尚不存在的项目。对于已有的应用，请使用下面的 onboard start。

要为现有应用添加 CopilotKit，可以按照快速开始操作，或者把这项任务交给你的编码 Agent：

npx copilotkit@latest onboard start --via skill:copilotkit-cli

这会在你当前所在的仓库上运行一个由 Agent 引导的流程，包含检查点和验证步骤，而不是脚手架。onboard start --intent <feature> 则针对已有 CopilotKit 的应用中的某一个功能。

登录并选择项目

npx copilotkit@latest login --json --via skill:copilotkit-cli   # agent-readable JSON lines, no browser launch
npx copilotkit@latest login --via skill:copilotkit-cli          # interactive: opens a browser
npx copilotkit@latest whoami --via skill:copilotkit-cli         # who is signed in, and the active organization
npx copilotkit@latest project select --via skill:copilotkit-cli # pick or create a hosted project for this directory
npx copilotkit@latest project list --json --via skill:copilotkit-cli

当你以编程方式驱动 CLI 时，请使用 login --json。裸 login 会尝试打开浏览器，这不是你能完成的。

没有 auth 命令。是 login。

project select 会将选择记录到 .copilotkit/project.json，并将项目作用域的运行时密钥写入 .env：

CPK_INTELLIGENCE_API_KEY=cpk_...

CPK_INTELLIGENCE_API_KEY 是规范名称，也是 CLI 唯一会写入的名称。请将其保留在服务端——它是运行时密钥，不是前端令牌，因此不需要 NEXT_PUBLIC_ 或 VITE_ 前缀。不要设置平台 URL：它们默认指向托管主机，因此你提供的任何值都只会用一个更差的值替换正确的默认值。

在没有 TTY 的情况下——编码 Agent 正是如此——使用 project list --json 查看选项，并使用 project select --project <id> 或 --create <name> 预先指定答案。

其他命令

命令	作用
skills install	将这些技能安装到项目中（skills onboard 还会启动引导）
typegen	从运行中的运行时生成类型安全的 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 可选择退出。