使用指南
CLI 命令行工具
在终端中使用 jsos 命令管理系统
JSOS 提供了命令行工具 jsos,让你可以在终端中直接管理系统,无需通过图形界面。
CLI 工具通过后台运行的 Daemon 进程与系统通信:
CLI 工具 (jsos)
↓ HTTP POST /api/jsos
Daemon (Express, port 1993)
↓ stdout/stdin 双向通信
主窗口 (浏览器)
↓ 执行 API 调用
↓ 返回结果
CLI 工具
Daemon 进程在 JSOS 启动时自动运行,提供 HTTP API 端点供 CLI 工具调用。
在 JSOS 终端中直接使用 jsos 命令:
# 查看系统信息
jsos api getSystemInfo
# 列出已安装应用
jsos app list
# 发送 Toast 通知
jsos toast --title "Hello from CLI" --type success
| 选项 | 说明 | 默认值 |
|---|
--port <port> | Daemon 端口 | 1993 |
| 命令 | 说明 | 示例 |
|---|
toast | 发送 Toast 通知 | jsos toast --title "完成" --type success |
toast 参数:
| 参数 | 必填 | 说明 |
|---|
--title <text> | ✓ | 标题 |
--description <text> | - | 描述 |
--type <type> | - | 类型:info、success、warning、error |
--duration <ms> | - | 显示时长(毫秒),默认 3000 |
jsos toast --title "下载完成" --description "文件已保存" --type success
jsos toast --title "警告" --type warning --duration 5000
| 命令 | 说明 | 示例 |
|---|
app list | 列出已安装应用 | jsos app list |
app info <appId> | 查看应用详情 | jsos app info dev.jsos.terminal |
app open <appId> | 打开应用 | jsos app open dev.jsos.terminal |
app open <appId> --route <route> | 打开应用并导航 | jsos app open dev.jsos.settings --route /wallpaper |
app close <appId> | 关闭应用 | jsos app close dev.jsos.terminal |
app running <appId> | 检查应用是否运行 | jsos app running dev.jsos.terminal |
app install <file> | 安装应用 | jsos app install ./my-app.zip |
app uninstall <appId> | 卸载应用 | jsos app uninstall my-app |
app uninstall <appId> --delete-data | 卸载并删除数据 | jsos app uninstall my-app --delete-data |
# 列出所有应用(运行中的应用会标记 ●)
jsos app list
# 安装本地 ZIP 文件
jsos app install ./my-app.zip
# 打开设置应用并导航到壁纸页面
jsos app open dev.jsos.settings --route /wallpaper
| 命令 | 说明 | 示例 |
|---|
workspace list | 列出工作区 | jsos workspace list |
workspace current | 查看当前工作区 | jsos workspace current |
workspace create <name> | 创建工作区 | jsos workspace create "工作" |
workspace switch <id> | 切换工作区 | jsos workspace switch ws-123 |
workspace delete <id> | 删除工作区 | jsos workspace delete ws-123 |
workspace rename <id> <name> | 重命名工作区 | jsos workspace rename ws-123 "办公室" |
# 列出所有工作区(当前工作区会标记 ●)
jsos workspace list
# 创建新工作区
jsos workspace create "项目开发"
| 命令 | 说明 | 示例 |
|---|
wallpaper get | 获取当前壁纸配置 | jsos wallpaper get |
wallpaper get --workspace <id> | 获取指定工作区壁纸 | jsos wallpaper get --workspace ws-123 |
wallpaper reset | 重置为默认壁纸 | jsos wallpaper reset |
wallpaper reset --workspace <id> | 重置指定工作区壁纸 | jsos wallpaper reset --workspace ws-123 |
# 查看当前壁纸配置
jsos wallpaper get
# 重置当前工作区壁纸
jsos wallpaper reset
| 命令 | 说明 | 示例 |
|---|
locale get | 获取当前语言 | jsos locale get |
locale set <lang> | 设置语言 | jsos locale set zh-CN |
# 查看当前语言
jsos locale get
# 切换到英文
jsos locale set en
| 命令 | 说明 | 示例 |
|---|
theme get | 获取当前主题 | jsos theme get |
theme set <mode> | 设置主题 | jsos theme set dark |
# 切换到暗色主题
jsos theme set dark
# 跟随系统主题
jsos theme set system
| 命令 | 说明 | 示例 |
|---|
proxy get | 获取代理配置 | jsos proxy get |
proxy set <url> | 设置代理 | jsos proxy set https://proxy.example.com |
proxy set <url> --key <key> | 设置代理(带密钥) | jsos proxy set https://proxy.example.com --key xxx |
proxy delete | 删除代理配置 | jsos proxy delete |
# 配置 CORS 代理
jsos proxy set https://cors-proxy.jsos.dev
# 删除代理配置
jsos proxy delete
| 命令 | 说明 | 示例 |
|---|
dock get | 获取 Dock 设置 | jsos dock get |
| 命令 | 说明 | 示例 |
|---|
terminal-bg get | 获取终端背景设置 | jsos terminal-bg get |
管理跨刷新持久化的用户数据目录(相对 workdir,如 .pi)。目录内容会被自动监听并快照到 IndexedDB,刷新页面或重启后自动恢复。
| 命令 | 说明 | 示例 |
|---|
persist list | 列出持久化目录及快照状态 | jsos persist list |
persist add <dir> | 新增持久化目录 | jsos persist add .pi |
persist rename <from> <to> | 重命名(数据迁移到新路径) | jsos persist rename .pi .pi-new |
persist remove <dir> [--purge] [-y] | 停止持久化(先确认;-y 跳过确认) | jsos persist remove .pi --purge |
# 让 ~/.pi 目录在刷新后保留
jsos persist add .pi
# 查看持久化目录与快照大小
jsos persist list
# 停止持久化(保留容器内文件与快照;会先确认一次)
jsos persist remove .pi
# 停止持久化并删除已存快照(-y 跳过确认)
jsos persist remove .pi --purge -y
注意:
remove 不会删除容器内的实际文件;默认保留快照(再次 add 同路径可恢复),--purge 才会删除快照。
remove 默认会先确认一次(输入 y 继续,其他取消);脚本中可用 -y/--yes 跳过确认。
- 相对路径按当前 shell 目录解析:
cd ~/test && jsos persist add ./data 持久化的是 test/data;~ 展开为 workdir。
- 重复添加同一目录是幂等的:输出
Already persistent: <dir> 并以 exit 0 结束;父子路径重叠会被拒绝。
workspace、.tmp 为保留前缀,不能作为持久化目录。
- 目录必须位于 WebContainer workdir(
$HOME,即 /home/<id>/)内部;workdir 之外的路径无法持久化,workdir 绝对路径会自动转换为相对路径。
在内置浏览器窗口中打开网址,或列出容器内运行的 HTTP 服务。
| 命令 | 说明 | 示例 |
|---|
browser open <url> | 在浏览器窗口打开 | jsos browser open https://example.com |
browser list | 列出内部 HTTP 服务 | jsos browser list |
# 打开容器内某个应用的页面
jsos browser open 127.0.0.1:4000
# 查看当前运行的内部服务
jsos browser list
说明: browser open 127.0.0.1:4000 会解析为容器内对应应用的地址(通过 listServers 映射),而不是用户本机的端口。
| 命令 | 说明 | 示例 |
|---|
data export | 导出所有系统数据 | jsos data export |
daemon dump | 导出 Daemon 快照(触发浏览器下载) | jsos daemon dump |
# 导出数据(输出 JSON)
jsos data export > backup.json
| 命令 | 说明 | 示例 |
|---|
restart | 重启 JSOS 系统 | jsos restart |
| 命令 | 说明 | 示例 |
|---|
api <type> [payload] | 直接调用任意 API | jsos api getApps |
# 调用任意 JSOS API
jsos api getApps
jsos api getWorkspaces
jsos api getAppInfo '{"appId":"dev.jsos.terminal"}'
# 列出所有运行中的应用
jsos app list | grep "●"
# 创建工作区并切换
jsos workspace create "新项目"
jsos workspace switch $(jsos workspace list | grep "新项目" | awk '{print $1}')
#!/bin/bash
# 备份工作区配置
jsos workspace list > workspaces.txt
jsos wallpaper get > wallpaper.json
jsos data export > system-data.json
# 检查系统状态
jsos api getSystemInfo
jsos app list
jsos workspace list
# 重置系统
jsos wallpaper reset
jsos theme set system
jsos locale set zh-CN
如果遇到 ECONNREFUSED 错误,说明 Daemon 进程未运行:
# 检查 Daemon 状态
jsos api getSystemInfo
# 如果 Daemon 未运行,重启 JSOS 系统
# 在图形界面中刷新页面即可
如果命令长时间无响应,可能是 Daemon 处理超时:
# 使用默认超时(30 秒)
jsos api getApps
# 如果数据量大,可能需要等待
jsos data export