CLI 使用

Soln CLI 是用于在终端登录 Soln 的命令行工具。

你可以使用它登录租户成员账号、查看当前会话并退出登录。

安装

通过 npm 安装：

npm install -g @soln/cli

安装后，可执行命令名为：

soln

检查命令是否可用：

soln help

查询版本

soln version

打印包名和已安装版本，例如 @soln/cli 0.1.0。soln --version、soln -v、soln -V 输出相同内容，soln version --json 返回 {"name":"@soln/cli","version":"..."}，方便脚本读取。

反馈问题或与控制面要求的 CLI 版本比对时，请带上这个版本号。

查看当前会话

soln whoami

这个命令会向 Soln 验证本地保存的会话，并显示当前成员和租户信息。

脚本或 AI Agent 调用时使用 JSON 输出：

soln whoami --json

JSON 结构示例：

{
  "authenticated": true,
  "callerType": "member",
  "email": "user@example.com",
  "tenant": {
    "id": "tenant-id",
    "subdomain": "acme",
    "type": "customer"
  },
  "expiresAt": "2026-05-28T12:00:00.000Z"
}

退出登录

soln logout

服务端确认退出后，CLI 会删除本地 token。

部署命令

soln 与 sl 是同一个 CLI 的两个命令名。首次安装使用 deployment 登录 → 登记 → 生成文件 → 安装，完整步骤见服务器单机安装和外部服务安装。

soln login 是日常 Runtime 操作登录；sl deployment login 是控制面部署授权，两者会话独立。部署授权需要租户成员具备 tenant.runtime.deployment.manage 权限。

部署登录、检查与退出

sl deployment login --base-url <控制面API地址> \
  --tenant <租户子域名> --email <成员邮箱> --method email
sl deployment status --json
sl deployment logout

邮箱验证码在终端输入；省略 --method email 则使用密码。部署会话保存在 ~/.soln/deployment-session.json，权限为 0600；不要分享其内容。deployment status 查看控制面登记，sl status --dir ... 查看本机实际安装，两者用途不同。

首次登记与生成部署文件

sl deployment register --dir /opt/soln-tenant-runtime \
  --deployment-target server --deployment-mode singleMachine \
  --runtime-origin https://runtime.example.com
sl deployment prepare --dir /opt/soln-tenant-runtime

外部服务模式登记时改用 --deployment-mode externalServices。本机部署使用 --deployment-target local，且只支持 singleMachine。登记会生成包含 Agent 密钥的 .soln-install-setup.json；deployment prepare 使用它和控制面登记生成部署文件。不要分享 setup 文件。

已有登记不能直接重做；register --force 会替换 Agent 凭证，仅用于明确的凭证替换操作。未完成安装复用原目录和 setup 文件；已安装目录使用升级命令。不要用 prepare --force 覆盖现有部署配置。

安装与自检

配置好 .env.example（或外部服务模式下的 .env）后执行：

sl install --dir /opt/soln-tenant-runtime \
  --setup-file /opt/soln-tenant-runtime/.soln-install-setup.json --yes
sl doctor --dir /opt/soln-tenant-runtime --json
sl status --dir /opt/soln-tenant-runtime --check --json

install 会先补齐身份信息和内置密钥，执行 doctor，再校验发布、迁移数据库并启动 Runtime。首次安装前手动 doctor 可能提示内置密钥尚未生成，不要用示例密钥绕过检查。安装成功后删除一次性 setup 文件并执行 sl deployment logout，保留 .env 和 .soln/deployment.json。

生命周期命令 install、doctor、status、upgrade、rollback 支持 --dir，省略时使用当前目录。登记、部署文件生成和更换域名要求显式 --dir；部署登录、登记查询和退出不使用这个参数。

升级与回滚

sl upgrade --dir /opt/soln-tenant-runtime --check
sl upgrade --dir /opt/soln-tenant-runtime --yes
sl rollback --dir /opt/soln-tenant-runtime

升级会备份 PostgreSQL；正常回滚会用该备份覆盖数据库，不保留备份后的写入，也不恢复对象存储或 Temporal 状态。回滚保留交互确认，完整规则见服务器升级与回滚。

更换访问域名

sl deployment origin --dir /opt/soln-tenant-runtime \
  --runtime-origin https://new-runtime.example.com

先 deployment 登录，并准备好可访问当前 Runtime 的新域名、HTTPS 和代理。该命令同步控制面登记和本地配置，重建 Runtime、Worker 并重启代理；仅支持未使用 Cloudflare Tunnel 的服务器部署。完整步骤见更换租户访问域名。

为 AI 或脚本提供输出

部署授权和生命周期命令支持 --json。AI 应先检查目标租户、目录和当前状态，再执行下一步；验证码和密码仍需终端交互输入，JSON 不会消除这些交互。遇到失败先保存错误码并停止，不要自动 register --force、覆盖配置或格式化磁盘。

运行时命令

运行时命令都在 sl system 下，例如列出某个工作区应用已安装的 MCP 服务：

soln system workspace-app mcp-server list --app-code <app-code>

所有命令都支持 --json 输出机器可读结果，完整目录见系统命令。

本地配置

CLI 会把会话数据保存到：

~/.soln/config.json

文件权限会设置为 0600。

保存字段包括：

baseUrl
callerType: "member"
email
token
sessionId
expiresAt
tenant

CLI 不会保存密码。

退出码

0：成功
1：网络或服务端错误
2：参数错误
3：未登录、会话过期或会话无效

安装​

查询版本​

登录​

查看当前会话​

退出登录​

部署命令​

部署登录、检查与退出​

首次登记与生成部署文件​

安装与自检​

升级与回滚​

更换访问域名​

为 AI 或脚本提供输出​

运行时命令​

本地配置​

退出码​

安装