cli-reference

Even Hub CLI 参考

安装

# Install as dev dependency (recommended)
npm install -D @evenrealities/evenhub-cli

# Install globally
npm install -g @evenrealities/evenhub-cli

# Or run without installing via npx
npx @evenrealities/evenhub-cli <command>

当前版本：v0.1.11

作为开发依赖安装时，使用 npx evenhub <command> 运行。全局安装时，直接使用 evenhub <command>。

---

evenhub login

使用 Even Hub 帐户进行身份验证。凭据会保存在本地，供日后使用。

evenhub login
evenhub login -e [email protected]

选项	描述
-e, --email <email>	帐户邮箱

---

evenhub init

生成初始版 app.json 清单文件。

evenhub init
evenhub init -d ./my-project
evenhub init -o ./config/app.json

选项	描述
-d, --directory <dir>	要创建文件的目录（默认：./）
-o, --output <path>	输出文件路径（覆盖 --directory）

---

evenhub qr

主要开发命令。生成指向本地开发服务的二维码。自动检测本地 IP，并在后续运行时记住之前的设置。

用手机上的 Even Realities App 扫描二维码，即可在眼镜上加载应用并启用热重载。

evenhub qr
evenhub qr --url "http://192.168.1.100:5173"
evenhub qr -i 192.168.1.100 -p 5173 --path /my-app
evenhub qr --url "http://192.168.1.100:5173" -e

选项	描述
-u, --url <url>	完整 URL（忽略其他 URL 选项）
-i, --ip <ip>	IP 地址或主机名
-p, --port [port]	端口号
--path <path>	URL 路径
--https	使用 HTTPS 而非 HTTP
--http	使用 HTTP（默认）
-e, --external	在外部程序中打开二维码，而非在终端中打开
-s, --scale <n>	文件输出的缩放比例（默认：4）
--clear	清除缓存的协议、IP、端口和路径

---

evenhub pack

将应用打包，以便在 Even Hub 上分发。

evenhub pack app.json dist -o myapp.ehpk
evenhub pack app.json ./build --check

参数/选项	描述
<json>	app.json 清单的路径
<project>	已构建输出文件夹的路径
-o, --output <file>	输出文件名（默认：out.ehpk）
--no-ignore	包含隐藏文件（点文件）
-c, --check	检查 Even Hub 上的 package_id 是否可用

---

Shell 补全

evenhub --completion-bash
evenhub --completion-zsh
evenhub --completion-fish

---

app.json 清单参考

字段表

字段	类型	必填	规则
package_id	string	是	反向域名格式，全部小写，不含连字符，至少 2 个部分，每个部分均以小写字母开头
edition	string	是	必须为 "202601"
name	string	是	最多 20 个字符
version	string	是	Semver 格式 x.y.z
min_app_version	string	是	最低 Even Realities App 版本（例如："2.0.0"）
min_sdk_version	string	是	最低 SDK 版本（例如："0.0.12"）
entrypoint	string	是	相对于构建文件夹的 HTML 入口文件路径
permissions	array	是	权限对象数组。可以是 []
supported_languages	array	是	有效值：en、de、fr、es、it、zh、ja、ko

模板

{
  "package_id": "com.example.myapp",
  "edition": "202601",
  "name": "My App",
  "version": "0.1.0",
  "min_app_version": "2.0.0",
  "min_sdk_version": "0.0.12",
  "entrypoint": "index.html",
  "permissions": [],
  "supported_languages": ["en"]
}

---

权限格式

权限是一个对象数组。每个对象都必须包含：

• name（string，必填）——权限标识符
• desc（string，必填）——描述，长度为 1-300 个字符
• whitelist（string[]）——仅适用于 network 权限

有效的权限名称： network、location、g2-microphone、phone-microphone、album、camera

常见错误： 权限必须是对象数组，而不是键值映射。

// Correct
"permissions": [
  { "name": "network", "desc": "Access the internet", "whitelist": ["https://api.example.com"] },
  { "name": "location", "desc": "Access device location" }
]

// Wrong — do NOT use a map/object
"permissions": {
  "network": "Access the internet"
}

---

故障排除（evenhub pack）

错误	解决方法
Invalid package id	使用小写反向域名格式，至少包含 2 个部分，不含连字符、大写字母或开头的数字
name: must be 20 characters or fewer	缩短应用名称
version: must be in x.y.z format	使用三段式 Semver 版本号
min_app_version/min_sdk_version: expected string, received undefined	两个字段均为必填项——将它们添加到 app.json
permissions: each permission must be an object	使用包含 name 和 desc 字段的对象数组
supported_languages: invalid language	使用支持列表中的小写 ISO 代码
Entrypoint file not found	确保文件存在于构建文件夹中
Project folder not found	先运行 npm run build

---

任务

$ARGUMENTS