CLI

North Coder 提供命令行工具 ncoder 和 north-coder，可以直接在终端完成服务管理、项目操作、Agent 交互和版本升级。CLI 是一层很薄的 HTTP 客户端，通过 REST API 与后端通信。

安装

CLI 随 North Coder 一起安装。ncoder 是推荐的短命令，north-coder 是等价的完整命令。安装完成后，在终端确认可用：

ncoder --version
north-coder --version

兼容场景中也可能存在 north-coder-server 软链，它指向同一个后端二进制。

命令总览

命令	用途	详细文档
`server`	管理本地后端进程	服务管理
`run`	一键发送任务给 Agent	快速运行
`project`	管理项目	资源管理
`workspace`	管理工作区	资源管理
`conversation`	管理会话（含 `search` / `siblings` / `tail`）	资源管理
`context`	查看当前会话的自身上下文 + 同 workspace 的兄弟会话	资源管理
`message`	发送消息、查询状态、获取结果、取消或提升队列任务	资源管理
`schedule`	管理会话级定时任务	资源管理
`permission`	审批暂停 invocation 上的工具权限请求	资源管理
`token` / `login` / `logout`	注入用户登录态 token，让 Agent 工具 CLI 带身份运行	登录态 Token
`config`	管理 CLI 持久配置	配置
`update`	检查和安装新版本	更新

全局选项

所有命令共享以下全局选项：

选项	默认值	说明
`--version`, `-V`	—	打印版本号并退出。
`--json`	`false`	输出机器可读 JSON。
`--server URL`	—	指定服务端地址，跳过自动发现。环境变量：`NC_SERVER`。
`--token TOKEN`	—	指定认证令牌。

示例：

# 普通输出
ncoder server status

# JSON 输出
ncoder --json server status

# 指定远程服务
ncoder --server http://192.168.1.10:8848 --token mytoken run "hello"

服务发现

CLI 通过多级优先级自动查找运行中的 North Coder 后端，无需每次手动指定地址。

优先级从高到低：

级别	来源	说明
1	`--server`	命令行显式指定。
2	`NC_SERVER` 环境变量	适合团队共享或 CI 场景。
2.5	`NORTH_CODER_SERVER` 环境变量	`NC_SERVER` 的低优先级兼容别名（运行时注入的是 `NC_SERVER`，此别名供人类手动 export / 前向兼容）。
3	CLI 配置文件	`~/.north-coder/cli-config.json` 中的 `server` 字段。
4	本地 daemon metadata	`~/.north-coder/server.json`，由桌面端或 `server start` 写入。
5	开发端口文件	开发模式生成的后端端口文件。
6	默认本地探测	探测 `127.0.0.1:8848`。

发现过程中，CLI 会对候选地址执行 health check（GET /api/health），只有返回有效 instance_id 的地址才会被采用。

安全策略

如果候选地址未通过 health check（unverified），CLI 不会将环境变量或配置文件中的 token 发送到该地址。
只有通过 --token 显式指定的令牌才会发送到 unverified endpoint。
这防止了因拼写错误或恶意 NC_SERVER 导致的凭证泄漏。

环境变量

变量	用途
`NC_SERVER`	服务端地址，等同 `--server`。
`NC_TOKEN`	认证令牌，由 discovery 在验证 endpoint 后使用。
`NORTH_CODER_SERVER`	`NC_SERVER` 的低优先级兼容别名（运行时注入的是 `NC_SERVER`）。
`NORTH_CODER_TOKEN`	`NC_TOKEN` 的低优先级兼容别名。
`NORTH_CODER_PROJECT_ID`	`workspace list` 省略参数时的默认 project id。
`NORTH_CODER_WORKSPACE_ID`	`conversation list` 省略参数时的默认 workspace id。
`NORTH_CODER_CONVERSATION_ID`	`conversation get` / `history` / `status` / `siblings` / `tail` 和 `context` 省略参数时的默认 conversation id。
`NC_AUTH_TOKEN`	daemon 内部使用的 API token（不建议手动设置）。
`NC_ADMIN_TOKEN`	daemon 内部使用的管理 token（不建议手动设置）。
`NC_DAEMON_MODE`	标识当前进程为 CLI daemon 子进程。

NORTH_CODER_PROJECT_ID / NORTH_CODER_WORKSPACE_ID / NORTH_CODER_CONVERSATION_ID 会被注入到 Agent 运行的 shell（RFC-0078），因此在 Agent 内调用 ncoder 时通常无需显式传 id。显式参数永远优先于环境变量。 详见资源管理 — 环境变量默认参数。

退出码

退出码	含义
`0`	成功。
`1`	业务错误（发现失败、HTTP 错误、验证失败、超时等）。
`2`	命令参数解析错误。

JSON 输出

使用 --json 时，CLI 将结果以 JSON 格式输出到 stdout。适合脚本集成和自动化：

# 获取服务状态
ncoder --json server status | jq .status

# 提交任务并获取 invocation ID
INVOCATION_ID=$(ncoder --json run "fix the bug" | jq -r .invocation_id)

错误信息仍输出到 stderr。

本页内容