# @botiverse/hands-cli 中文文档

规范地址：https://npmcn.com/package/%40botiverse/hands-cli/

版本：0\.5\.43
npm 元数据更新时间：2026-11-08T09:46:17.753Z
中文译文更新时间：2026-11-08T12:25:18.084Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40botiverse/hands-cli
原文对照：https://npmcn.com/package/%40botiverse/hands-cli/?lang=original
项目主页：https://github.com/botiverse/hands#readme
源码仓库：https://github.com/botiverse/hands

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：642 kB，91 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：3 个
- 首次发布：2026-07-09T11:15:48.255Z
- 最新版本发布：2026-11-08T09:46:17.261Z
- 近 30 天下载量：2697（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：40（近 12 个月 40 个）

## 中文简介

Hands CLI——管理终端的应用,构建,发布.

## 安装

```sh
npm install @botiverse/hands-cli
```

也可以使用：`pnpm add @botiverse/hands-cli`、`yarn add @botiverse/hands-cli`、`bun add @botiverse/hands-cli`

## README

# @botiverse/ hands-cli (英语)

Hands CLI——管理终端的应用,构建,发布.

状态 : **阿尔法**。 npm 软件包以 `@botiverse/hands-cli`; v1 舰只 `login`, (中文(简体) ), `logout`, (中文(简体) ), `whoami`, (中文(简体) ), `apps create/list/get/client-key`, (中文(简体) ), `builds list/get`,以及 `builds publish-version`, (中文(简体) ), `builds publish-android`, (中文(简体) ), `builds publish-ios`, (中文(简体) ), `builds testflight-groups`, (中文(简体) ), `builds testflight-publish`, (中文(简体) ), `builds testflight-status`, (中文(简体) ), `builds publish-ohos`,以及 `builds publish-electron`。 。 。 . 列出的其他命令 `docs/cli-reference.md` 随着后端终点的出现,土地逐渐增加.

## 安装

```bash
npm install -g @botiverse/hands-cli
hands --help

# Or run without installing globally:
npm exec --package @botiverse/hands-cli@0.5.15 -- hands --help

# Local repo development:
pnpm --filter @botiverse/hands-cli build
pnpm --filter @botiverse/hands-cli start -- whoami
```

## 快速启动

```bash
# 1. Log in. The CLI prints a URL you must open in a browser.
hands login

# 2. Verify who you are.
hands whoami

# 3. Create or list apps in your current Hands organization.
hands apps create --slug hands-example-web --name "Hands Example Web" --platform web
hands apps list

# Read the public SDK client key explicitly (app admin only).
hands apps client-key hands-example-web

# 4. List builds for an app (by slug or id).
hands builds list myapp-android

# 5. Publish an Android APK release.
hands builds publish-android raft-android \
  --channel main \
  --apk ./app-release.apk \
  --version-name 1.0.3 \
  --version-code 1000300
```

用于将文物留在外部CDN的节点应用软件,注册一个 一次不可改变的目标声明:

```bash
hands builds publish-version raft-computer \
  --version-name 0.72.13 \
  --target darwin-arm64 \
  --source-url https://cdn.raft.build/computer/0.72.13/darwin-arm64 \
  --raw-sha256 "$RAW_SHA256" --raw-size "$RAW_SIZE" \
  --gzip-sha256 "$GZIP_SHA256" --gzip-size "$GZIP_SIZE" \
  --node-version 22.23.1
```

此记录外部字节证据; 它不上传文物或 启动释放。 复说同相宣说能入正等正觉. 更改一个 永久版本或目标字段返回冲突.

## 直接 API 访问( E)`hands api`(中文(简体) )

直接在同一个服务器侧RBAC上呼叫任何Hands端点并审计 a 专用子命令使用——脚本支付,而不是权限绕行 :

```bash
hands api GET /api/apps --param platform=android
hands api PATCH /api/apps/<appId>/releases/<releaseId>/shares/<shareId> --data '{"expires_at":null}'
hands api PATCH /api/apps/<appId>/releases/<releaseId>/shares/<shareId> --data @body.json
hands api GET /api/apps/<appId>/feedback/<ticketId>/attachments/<attachmentId> --output attachment.bin
hands --json api GET /api/apps                                               # body only
```

路径参数为生- `<appId>` 而其他的ID是资源UUID,而不是sults (单位:千美元)`hands api` 不解决弹壳。 同一来源 `/api/*` 只( 相对路径) 或同一来源的绝对URL; 交叉来源, `//protocol-relative`,以及 `../`\- 逃脱被拒绝). 指示从不跟随,所以传令者从不 离开手源。 荣耀全球 `--api` 财务报告和审定财务报表 `--json` 旗帜。 满旗 参考文献 : [https://hands.building/docs/cli-参考文献/](https://hands.build/docs/cli-reference/)。 。 。 .

## CI 模式

```bash
export HANDS_API=https://hands.build
export HANDS_AUTH_TOKEN=...       # Hands JWT or an app deploy token
hands whoami
hands builds list myapp-android
```

## 认证工作方式( v1)

Raft OAuth使用浏览器重定向. 手将成功的登录转换为 签字的JWT,所以 `hands login` 请您:

1.  在任意浏览器中打开已打印的 URL .
2.  和拉夫签约.
3.  复制 Hands CLI 回调页面显示的 JWT .
4.  把它贴回CLI.

JWT被保存到 `$XDG_CONFIG_HOME/quiver/auth.json` (第0600节). CI,通过 `HANDS_AUTH_TOKEN` 或者说 `HANDS_BEARER_TOKEN`遗产 `QUIVER_*` 现有自动化仍然接受别名.

v2 将转换为真实的无头流( Raft 设备流或 a) `--token-stdin` 服务用户模式)。 见 `publish-tasks.md` P3.4.x (中文(简体) ).

## 本地日志

CLI 将 JSONL 日志编辑为最佳 `$XDG_STATE_HOME/hands/logs` (或 `~/.local/state/hands/logs`) (中文(简体) ). 日志失败 绝不更改命令输出或退出状态。 覆盖目录 `HANDS_LOG_DIR`。 。 。 .

创建 gzip 捆绑, 只有在您有签名、 未过期的收藏策略和 ed25519公用钥匙:

```bash
hands logs collect \
  --policy ./collect-policy.json \
  --public-key ./hands-log-policy-public.pem \
  --output ./hands-logs.json.gz
```

政策签名 版本 过期 降级状态 编辑 每日大小, 每个收集规模、货币和网络预算在当地执行. 拒绝的收藏保存失败关闭, 不更改审计日志 cLI 进程退出行为 .

## 常见问题

### @botiverse/hands-cli 是什么？

Hands CLI——管理终端的应用,构建,发布\.

### 如何安装 @botiverse/hands-cli？

在项目目录运行 npm install @botiverse/hands-cli，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 hands、quiver，可以用 npx hands 直接运行。

### @botiverse/hands-cli 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @botiverse/hands-cli 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @botiverse/hands-cli 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @botiverse/hands-cli 可以商用吗？

@botiverse/hands-cli 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @botiverse/hands-cli 的下载量有多少？

根据 npm 官方下载统计，@botiverse/hands-cli 在 2026/10/09 – 2026/11/07 这 30 天内被下载 2,697 次，日均约 90 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @botiverse/hands-cli 还在维护吗？

最新版本 0\.5\.43 发布于 2026/11/08（今天）；至今共发布 40 个版本，其中过去 12 个月发布了 40 个；首次发布于 2026/07/09。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。