CLI

keon 是面向 Kisenon 平台的直接替换式 neonctl 形态客户端。

在 macOS / Linux 上安装

curl -fsSL https://kisenon.com/install.sh | sh

检测你的平台，下载匹配的 keon-<os>-<arch> 二进制文件，根据 /dl/latest/manifest.json 校验 sha256，然后安装到 ~/.local/bin（若 /usr/local/bin 可写，例如以 root 运行，则安装到那里）。如果该目录不在 PATH 中，脚本会把它写入你的 shell rc 文件。脚本是 POSIX sh，不需要 bash。

在 Windows 上安装

主要渠道是 winget：

winget install Seiraiyu.Keon

或直接运行安装脚本：

irm https://kisenon.com/install.ps1 | iex

它安装到 %LOCALAPPDATA%\keon，并将其加入用户 PATH。

安装程序环境变量

并非每个变量两个脚本都会读取——Scripts 列说明由哪个读取。使用 curl | sh 时，要设置在 sh 一侧： curl -fsSL https://kisenon.com/install.sh | KEON_INSTALL_DIR=/opt/bin sh.

Variable	Scripts	Default
`KEON_INSTALL_VERSION`	两者	`latest`	固定版本，例如 `v0.1.56`。
`KEON_INSTALL_DIR`	两者	`~/.local/bin` (sh), `%LOCALAPPDATA%\keon` (PowerShell)	安装目录。同时跳过 `/usr/local/bin` 回退。
`KEON_INSTALL_NO_PATH`	两者	—	设为 `1` 跳过 `PATH` 修改。
`KEON_INSTALL_HOST`	两者	`https://kisenon.com`	下载主机。必须是 `https://`。
`KEON_CONFIG_DIR`	两者	`~/.config/keon`	`host` 文件的写入目录。在 Windows 上 `KEON_HOST_FILE` 优先。
`KEON_HOST_FILE`	仅 `install.ps1`	`~/.config/keon/host`	`host` 文件路径。
`KEON_API_URL_DEFAULT`	两者	`https://kisenon.com`	安装时写入 `host` 文件的 API 主机。
`KEON_UNINSTALL`	两者	未设置	`1` 删除二进制文件和 `PATH` 代码块，凭据保留。
`KEON_INSTALL_FORCE`	仅 `install.sh`	未设置	`1` 即使已安装版本一致也重新下载。`install.ps1` 根本没有版本一致跳过——它每次运行都会重新下载，因此这个变量无从强制。

首次登录

keon login
keon me

keon login 运行一个回环 OAuth 流程 —— 无需粘贴密钥。它在一个随机端口上启动一个本地监听器，打开你的浏览器到控制台的授权页面，然后等待重定向。在你授权之后，CLI 会在 POST /v1/cli/exchange 处将一次性 code 换取一个长期的、以 nsk_ 为前缀的 API 密钥，其作用域限定为你的活跃组织。

该密钥以 0600 模式持久化到 ~/.config/keon/credentials.json。 CLI 只保留最终得到的密钥 —— 从不保留 OAuth code、 state 或任何提供方令牌。keon logout 会删除该文件，并尝试在服务器端吊销密钥（尽力而为：失败时只警告，仍以 0 退出）；你也可以随时从设置 → API 密钥吊销它。参见身份验证了解完整流程。

在 Windows 上，该文件位于 %USERPROFILE%\.config\keon\credentials.json； 0600 模式在那里不适用，文件继承你的配置文件 ACL —— 仅你的用户、SYSTEM 和 Administrators 可访问。

常用命令

keon projects list
keon branches list --project <id>
keon connection-string <branch> --project <id>

无论默认输出格式如何，keon connection-string 都只打印直连 URI （因此 psql "$(keon connection-string main --project <id>)" 可直接使用）。--pooled 改为打印连接池 URI；若端点未启用连接池，则以 pooler_not_enabled 退出并返回 1。 -o json 返回 {"connection_string": "…"}。

删除一个项目也会删除其分支和端点 —— 传入 --cascade；否则只要项目还有 main 以外的分支，API 就会返回 409 has_branches：

keon projects delete <id> --cascade

同样的 --cascade 标志适用于 keon branches delete <id>。

keon status

keon status

报告 CLI 是否持有可用的凭据。它会用 /v1/auth/whoami 校验密钥，因此被吊销或过期的密钥会报告 authenticated: false，而不是过时的成功。响应体始终包含 .authenticated 和 latencyMs；使用已保存的凭据时，还会填入 api_url、user 和 token_id。

脚本应当判断的是退出码：

Exit
`0`	已认证——密钥已通过 `/v1/auth/whoami` 校验。
`1`	未认证——没有凭据，或 cp 返回 `401`/`403`。
`2`	无法判断——连接被拒绝、DNS 失败、超时，或 `5xx`。

2 故意不等于 1：控制平面不可达并不能证明你的凭据有问题，而 keon status && deploy.sh 在两种情况下都必须停止。请直接读取退出码——把 keon status 通过管道传给其他命令会用管道的退出码替换它。

智能体工作流

keon 覆盖智能体安全面，而不仅仅是项目和分支：

keon sandbox —— 驱动智能体沙箱：面向智能体的临时性、捕获并提升的数据库环境。
keon ledger —— 读取提升账本并验证捕获/提升的证明。
keon ip-allow —— 管理项目的 IP 白名单。

其他顶级命令包括 orgs、endpoints、databases、 roles、snapshots、operations、usage 和 audit。运行 keon --help 查看完整集合。

输出格式

默认是 JSON。若要表格：keon config set output table，或按命令传入 --output table。

安装 Claude 技能

keon install --skills

将一个 SKILL.md 加参考文档放入 ./.claude/skills/keon/，使得 Claude 智能体无需一轮设置即可驱动 CLI。

疑难解答

macOS：“developer cannot be verified”

仅当二进制文件是通过浏览器下载并带有 Gatekeeper 属性时才会发生（install.sh 不会设置该属性）。去除它：

xattr -d com.apple.quarantine $(which keon)

Windows：SmartScreen 警告

点击 “More info” → “Run anyway”。每台机器一次。通过 winget install Seiraiyu.Keon 安装可避免该提示。Windows 构建的 SmartScreen 信誉会随时间建立。

Windows：`winget upgrade` 提示软件包“已被修改”

如果 0.1.59 或更早版本的 keon update 替换了 winget 安装的二进制文件， winget upgrade Seiraiyu.Keon 会失败并提示 Unable to remove Portable package as it has been modified。winget 在安装时记录了原始文件的哈希，并拒绝覆盖已更改的文件。执行一次以跳过该检查：

winget upgrade Seiraiyu.Keon --force

之后 winget list 与 keon --version 会重新一致。当前的 keon 会拒绝对 winget 安装进行自更新，因此不会再次出现此问题。