JSOS
使用指南

CLI 命令行工具

在终端中使用 jsos 命令管理系统

CLI 命令行工具

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 设置

命令说明示例
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 调用

命令说明示例
api <type> [payload]直接调用任意 APIjsos 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

故障排除

无法连接 Daemon

如果遇到 ECONNREFUSED 错误,说明 Daemon 进程未运行:

# 检查 Daemon 状态
jsos api getSystemInfo

# 如果 Daemon 未运行,重启 JSOS 系统
# 在图形界面中刷新页面即可

命令无响应

如果命令长时间无响应,可能是 Daemon 处理超时:

# 使用默认超时(30 秒)
jsos api getApps

# 如果数据量大,可能需要等待
jsos data export

相关文档

On this page