KCode CLI

kcode-cli 用来启动本地 KCode 服务。默认模式下会同时提供内置的 Web UI，因此安装后通常只需要执行一个命令就能开始使用。

环境要求

• Node.js >= 20

安装

全局安装：

npm install -g kcode-cli

安装完成后可直接使用：

kcode --help

如果只是临时运行一次，也可以使用：

npx kcode-cli --help

最快启动

在当前目录启动 API 和内置 Web UI：

kcode

这等价于：

kcode web

默认值：

• Host: 127.0.0.1
• Port: 4096
• Directory: 当前工作目录

启动模式

kcode

默认等价于 kcode web，会同时启动：

• 本地 API 服务
• 内置 Web UI

适合直接在浏览器里使用 KCode。

kcode serve

只启动 API 服务，不挂载内置 Web UI。

适合：

• 只把 KCode 当本地后端使用
• 由自己的客户端或脚本连接 API
• 需要把 Web UI 与 API 分开处理

常见场景

在当前目录直接使用

kcode

打开指定项目目录

kcode --directory E:\project\demo

只启动 API

kcode serve

改端口运行

kcode --port 4310

对局域网开放

kcode --hostname 0.0.0.0 --port 4310

如果要从其他设备访问，请在浏览器里使用这台机器的实际 IP，例如 http://192.168.1.10:4310。

同时指定目录、主机和端口

kcode web --directory E:\project\demo --hostname 127.0.0.1 --port 4310

命令与参数

Usage: kcode [web|serve] [options]

Commands:
  web              Start the API and bundled web UI (default)
  serve            Start the API only

Options:
  --hostname <host>    Bind address (default: 127.0.0.1)
  --port <port>        Bind port (default: 4096)
  --directory <path>   Override project directory (default: current working directory)
  --log-level <level>  Accepted for SDK compatibility
  -h, --help           Show this message

支持两种写法：

kcode --port 4310
kcode --port=4310

环境变量

可以用环境变量设置默认值：

| 变量 | 默认值 | 作用 | | ---- | ------ | ---- | | KCODE_DIRECTORY | 当前工作目录 | 默认项目目录 | | KCODE_SERVER_HOST | 127.0.0.1 | 默认监听地址 | | KCODE_SERVER_PORT | 4096 | 默认监听端口 |

优先级如下：

1. CLI 参数
2. 环境变量
3. 内置默认值

示例：

KCODE_DIRECTORY=E:\project\demo KCODE_SERVER_PORT=4310 kcode

默认行为

• 不传子命令时，默认使用 web 模式
• 不传 --directory 时，使用当前工作目录
• 不传 --hostname 时，使用 127.0.0.1
• 不传 --port 时，使用 4096
• --log-level 当前仅用于 SDK 兼容，不会改变 CLI 输出行为

排查

端口被占用

换一个端口重试：

kcode --port 4310

想确认实际参数

先看帮助：

kcode --help

需要仓库源码或开发说明

如果你是在仓库源码里阅读这份文件，可以继续看：

• 根目录 README.md
• docs/README.md