@kmax/w3-app

通过 home-w3 Server HTTP API 管理托管应用和链接应用的 TypeScript CLI。使用前需要准备可访问的 Server 地址和管理 Token。

安装

需要 Node.js 22.12 或更高版本。通过 npm 全局安装：

npm install -g @kmax/w3-app
w3-app --help

命令

全局命令为 w3-app。常用操作：

w3-app health
w3-app list
w3-app get demo-app
w3-app create ./dist --id demo-app -n "Demo App" -c WebGL
w3-app create https://pm.example.com/ --link --id project-links -n "友情链接"
w3-app update demo-app -n "New Name"
w3-app update demo-app -s ./dist
w3-app update demo-app -s ./dist -n "New Name"
w3-app update project-links --url https://pm2.example.com/
w3-app delete demo-app

create 默认使用 --hosted，其源路径和 update -s, --source 均接受 ZIP 或静态网站目录。目录会在系统临时目录打包，ZIP 根目录直接对应网站根目录；符号链接会被拒绝。使用 --link 时，源参数必须是完整的 HTTP(S) URL，且不能同时指定 --hosted 或 --category。

create 的 --id 必填，-n, --name 省略时默认使用 ID。应用类型创建后不可修改。update 可使用 --url 修改链接地址，或使用 --source 替换托管内容，两者不能同时使用；名称和描述对两类应用均可修改，分类仅适用于托管应用。

删除应用会要求输入应用 ID；在 CI/CD 等非交互环境中必须显式使用：

w3-app delete demo-app --yes

所有业务命令支持 --json。JSON 只写入 stdout，错误和阶段信息写入 stderr。

配置

配置优先级从高到低为：

1. --server / --token；
2. W3_APP_SERVER / W3_APP_TOKEN；
3. 当前目录 w3-app.config.json；
4. 用户持久化配置；
5. 默认地址 http://127.0.0.1:5555。

用户持久化配置位于：

• Windows：%APPDATA%\w3-app\config.json；
• macOS：~/Library/Application Support/w3-app/config.json；
• Linux：$XDG_CONFIG_HOME/w3-app/config.json，未设置时为 ~/.config/w3-app/config.json。

使用配置命令管理用户级配置：

w3-app config set server https://apps.example.com
w3-app config set token replace-with-a-long-random-token
w3-app config list
w3-app config path
w3-app config unset token

增加 --local 后操作当前目录的 w3-app.config.json。配置文件允许保存明文 Token，请勿提交包含 Token 的配置文件。config get/list 默认遮蔽 Token，只有显式使用 --show-token 才显示完整值。