命令参考

更新于 2026年11月10日

所有命令的写法均为 konsolity <command> [options]。konsolity help 和 konsolity <command> --help 会以系统语言显示帮助。--json 输出格式稳定,供脚本使用;其中从不包含任何机密。

概览

命令 所需的域 作用
login 激活机器(激活机器)
setup-token 为 CI 和容器创建长期令牌
status 账户、机器、范围、有效期、状态
hosts hosts 范围内的主机
run hosts,完全访问 在主机上运行命令
snippet list snippets 范围内的代码片段
snippet run snippets + hosts,完全访问 在主机上运行代码片段
sessions sessions 账户中正在运行的 CLI 会话
sessions end sessions 结束会话
mcp mcp 用于 Claude Code 的本地 MCP 服务器(本地 MCP)
serve mcp + Claude 集成 处理 Claude 连接器的请求(服务)
service install 将 serve 安装为系统服务
rotate 续期机器的令牌
policy 显示实际执行的范围和规则
logout 撤销机器并清除所有本地数据
version 版本、系统、架构
update 更新二进制文件(校验签名)

范围之外的命令会返回 scope_denied;在只读机器上运行命令会返回 read_only。

login

konsolity login [--name <name>] [--scopes hosts,snippets,sessions,mcp] [--read-only]

使用从您的账户批准的代码激活机器。详情和示例:激活机器。

setup-token

konsolity setup-token [--name <name>] [--scopes <list>] [--read-only]

流程与 login 相同,但不保存任何内容,而是仅显示一次 ksetup_... 令牌。之后通过 KONSOLITY_TOKEN 提供该令牌。参阅 setup-token。

status

konsolity status [--json]

显示账户、机器的名称和类型、范围(域,只读或完全访问)、有效期、令牌的存在时长、服务器状态以及可访问的主机数量。

$ konsolity status
Account       anthony@example.com
Machine       build-01 (machine)
Scope         hosts, snippets, mcp · full access
Expires on    2027-02-08
Token         renewed 3 h ago
Server        api.konsolity.com · reachable
Hosts         4

hosts

konsolity hosts [--json]

列出范围内的主机:标签、地址、用户、分组。从不显示密码或密钥。

$ konsolity hosts
web-01     203.0.113.10   deploy   Production
web-02     203.0.113.11   deploy   Production
db-01      10.0.0.5       admin    Data

run

konsolity run <host> [--timeout <seconds>] [--json] -- <command>

通过 SSH 在主机上运行命令:使用专用的短连接,要求已固定的主机密钥,在终端中实时输出,并将远程命令的退出码作为 konsolity 的退出码返回。<host> 是主机的标签或标识符。-- 之后的所有内容都将原样作为命令。

选项 作用
--timeout <seconds> 命令的超时时间,以机器的最大超时时间为上限(默认 60 秒)。
--json 结束时输出单个 JSON:exit_code、stdout、stderr、duration_ms。
$ konsolity run web-01 -- systemctl status nginx
● nginx.service - A high performance web server
     Active: active (running) since Mon 2026-11-09 08:12:44 UTC
$ echo $?
0

运行命令之前,CLI 会检查范围和规则,然后将开始记录写入日志:如果写入失败,命令不会运行。破坏性命令会等待您的确认:

$ konsolity run db-01 -- "mysql -e 'DROP TABLE sessions_old'"
Destructive command: confirmation requested in the Konsolity app.
https://app.konsolity.com/cli/confirm/9f3c2a71
Waiting (5 min at most)...
Allowed. Running.

snippet

konsolity snippet list [--json]
konsolity snippet run <snippet> <host> [--timeout <seconds>] [--json]

snippet list 显示范围内的代码片段(名称、分组)。snippet run 在范围内的主机上按保险库中保存的内容运行代码片段。<snippet> 是其名称或标识符。适用与 run 相同的规则:记录日志,内容具有破坏性时需要确认,返回退出码。

$ konsolity snippet run "Clear the cache" web-01
Cache cleared.

sessions

konsolity sessions [--follow] [--json]
konsolity sessions end <id>

列出账户中正在运行的 CLI 会话:机器、命令、持续时间。--follow 会保持列表打开并持续刷新。sessions end <id> 结束一个会话:对应的命令会在 5 秒内停止。

$ konsolity sessions
a1b2c3   build-01   run web-01: tail -f /var/log/nginx/access.log   for 12 min
d4e5f6   laptop     mcp                                             for 1 h
$ konsolity sessions end a1b2c3

mcp

konsolity mcp

启动一个本地 stdio MCP 服务器,用于连接到 Claude Code:

claude mcp add konsolity -- konsolity mcp

工具和限制的详细说明:用于 Claude Code 的本地 MCP。

serve

konsolity serve

像桌面应用一样处理账户中 Claude 连接器(claude.ai、Claude 应用)的请求,但没有界面,并遵循范围和规则。需要 mcp 域和 Studio 套餐的 Claude 集成。该命令在前台运行;在服务器上,请将其安装为服务。

service install

sudo konsolity service install

将 konsolity serve 安装为系统服务(systemd、launchd 或 Windows 计划任务)。参阅服务与存储。

rotate

konsolity rotate

强制续期机器令牌。无论如何,令牌每 24 小时都会自动轮换。机器密钥不会改变。

policy

konsolity policy [--json]

显示机器实际执行的内容:域、只读或完全访问、主机、代码片段、命令规则、“任意命令”、最大超时时间。

logout

konsolity logout

在服务器上撤销该机器,然后清除令牌、机器密钥和本地副本。如需再次使用该机器,需要重新激活。

version

konsolity version

显示版本、系统和架构。

update

konsolity update

下载最新版本,校验其 SHA-256 哈希值和清单的 Ed25519 签名,然后替换二进制文件。如果是通过 apt、dnf 或 Homebrew 安装的,CLI 会提示您使用相应的包管理器。

环境变量

变量 作用
KONSOLITY_TOKEN 长期令牌 ksetup_...(CI、容器)。取代已保存的机密。

退出码

代码 含义
0 成功。
远程代码 run 和 snippet run 以远程命令的退出码退出(例如命令在主机上失败时为 1)。
1 一般错误:机器未激活、网络不可达、找不到主机或片段、日志行未写入(此时命令不会启动)、本地机密无法读取。
2 用法错误:未知选项、缺少命令或命令过长(最多 4000 个字符)、KONSOLITY_TOKEN 无效。
3 拒绝:范围中缺少该域(scope_denied)、机器为只读(read_only)、没有匹配的规则(denied)、缺少规则(policy_missing)、需要套餐(plan_required)或激活被拒绝。
4 破坏性命令未获确认:在应用或控制台中被拒绝,或 5 分钟内无人回应。命令未启动。
77 机器已被撤销、已过期或在另一台电脑上使用(指纹不同),或会话已从应用或控制台结束:连接被切断,命令被停止。除单纯结束会话的情况外,本地机密也会被清除。