命令参考
所有命令的写法均为 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 |
机器已被撤销、已过期或在另一台电脑上使用(指纹不同),或会话已从应用或控制台结束:连接被切断,命令被停止。除单纯结束会话的情况外,本地机密也会被清除。 |