abcli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

abcli — AstroBox CLI

abcli is the official command-line interface for AstroBox. Any task that involves controlling or querying AstroBox should go through abcli rather than direct file manipulation or API calls.

abcli 是 AstroBox 的官方命令行界面（CLI）。任何涉及控制或查询 AstroBox 的任务都应通过 abcli 完成，而非直接操作文件或调用 API。

Installation

安装

abcli is distributed on npm as

astrobox-cli

. Always run it via npx — no global installation needed:

bash

npx astrobox-cli <command> [options]

If the user has it installed locally in the project, use the local binary:

bash

pnpm cli <command>   # if in AstroBoxCli repo

Requires Node.js >= 20 and the AstroBox desktop app to be running.

abcli 以

astrobox-cli

的名义发布在 npm 上。请始终通过 npx 运行它——无需全局安装：

bash

npx astrobox-cli <command> [options]

如果用户已在项目中本地安装了它，请使用本地二进制文件：

bash

pnpm cli <command>   # if in AstroBoxCli repo

需要 Node.js >= 20，且 AstroBox 桌面应用处于运行状态。

When to use

使用场景

Use abcli for any AstroBox-related task:

Launching AstroBox (
```
open
```
)
Checking if AstroBox is running / listing connected devices (
```
status
```
)
Managing saved devices: list, show details, connect new ones (
```
device
```
)
Browsing resource providers: list providers, check state, categories, refresh (
```
provider
```
)
Searching/filtering resources by page, keyword, category, sort (
```
provider page
```
)
Getting resource details and download links (
```
provider item
```
,
```
provider download
```
)
Installing local resource files (
```
install
```
)

Do not use abcli when:

AstroBox is not installed or not running (API at
```
127.0.0.1:10721
```
will be unreachable)
The user explicitly asks to edit AstroBox source code or config files directly

任何与 AstroBox 相关的任务都可使用 abcli：

启动 AstroBox（
```
open
```
命令）
检查 AstroBox 是否运行 / 列出已连接设备（
```
status
```
命令）
管理已保存设备：列出设备、查看详情、连接新设备（
```
device
```
命令）
浏览资源提供商：列出提供商、检查状态、查看分类、刷新内容（
```
provider
```
命令）
按页码、关键词、分类、排序方式搜索/筛选资源（
```
provider page
```
命令）
获取资源详情和下载链接（
```
provider item
```
、
```
provider download
```
命令）
安装本地资源文件（
```
install
```
命令）

请勿使用 abcli 的场景：

AstroBox 未安装或未运行（位于
```
127.0.0.1:10721
```
的 API 无法访问）
用户明确要求直接编辑 AstroBox 源代码或配置文件

Quick reference

快速参考

Task	Command
Launch AstroBox	`npx astrobox-cli open`
Check status	`npx astrobox-cli status`
List devices	`npx astrobox-cli device list`
Show device details	`npx astrobox-cli device show <addr>`
Connect device	`npx astrobox-cli device connect --name "..." --addr "..." --authkey "..."`
List providers	`npx astrobox-cli provider list`
Provider state	`npx astrobox-cli provider state <name>`
Categories	`npx astrobox-cli provider categories <name>`
Refresh provider	`npx astrobox-cli provider refresh <name>`
Total items	`npx astrobox-cli provider total <name>`
Browse page	`npx astrobox-cli provider page <name> --category ... --sort time`
Search by keyword	`npx astrobox-cli provider page <name> --keyword <keyword>`
Item detail	`npx astrobox-cli provider item <name> <id>`
Download link	`npx astrobox-cli provider download <name> --id <id> --device <key>`
Install local file	`npx astrobox-cli install <path>`

任务	命令
启动 AstroBox	`npx astrobox-cli open`
检查状态	`npx astrobox-cli status`
列出设备	`npx astrobox-cli device list`
查看设备详情	`npx astrobox-cli device show <addr>`
连接设备	`npx astrobox-cli device connect --name "..." --addr "..." --authkey "..."`
列出资源提供商	`npx astrobox-cli provider list`
查看提供商状态	`npx astrobox-cli provider state <name>`
查看分类	`npx astrobox-cli provider categories <name>`
刷新提供商内容	`npx astrobox-cli provider refresh <name>`
查看总资源数	`npx astrobox-cli provider total <name>`
浏览指定页码资源	`npx astrobox-cli provider page <name> --category ... --sort time`
按关键词搜索	`npx astrobox-cli provider page <name> --keyword <keyword>`
查看资源详情	`npx astrobox-cli provider item <name> <id>`
获取下载链接	`npx astrobox-cli provider download <name> --id <id> --device <key>`
安装本地文件	`npx astrobox-cli install <path>`

Core workflows

核心工作流

Workflow: Connect a new device

工作流：连接新设备

bash

npx astrobox-cli device list                          # see existing devices
npx astrobox-cli device connect \
  --name "Xiaomi Smart Band 9 Pro C692" \
  --addr "3C:AF:B7:ED:C6:92" \
  --authkey "your-authkey"                            # user must tap confirm on device
npx astrobox-cli device show 3C:AF:B7:ED:C6:92      # verify

bash

npx astrobox-cli device list                          # 查看现有设备
npx astrobox-cli device connect \
  --name "Xiaomi Smart Band 9 Pro C692" \
  --addr "3C:AF:B7:ED:C6:92" \
  --authkey "your-authkey"                            # 用户需在设备上点击确认
npx astrobox-cli device show 3C:AF:B7:ED:C6:92      # 验证连接

Workflow: Find and download a resource

工作流：查找并下载资源

bash

npx astrobox-cli provider list                        # pick provider
npx astrobox-cli provider refresh OfficialV2          # refresh cache before search
npx astrobox-cli provider page OfficialV2 \
  --keyword "search-term" --limit 20                 # search by keyword
npx astrobox-cli provider item OfficialV2 <id>        # inspect details, get device key
npx astrobox-cli provider download OfficialV2 \
  --id <id> --device <key>                           # get download URL

bash

npx astrobox-cli provider list                        # 选择资源提供商
npx astrobox-cli provider refresh OfficialV2          # 搜索前刷新缓存
npx astrobox-cli provider page OfficialV2 \
  --keyword "search-term" --limit 20                 # 按关键词搜索
npx astrobox-cli provider item OfficialV2 <id>        # 查看详情，获取设备密钥
npx astrobox-cli provider download OfficialV2 \
  --id <id> --device <key>                           # 获取下载URL

Workflow: Full install (search → download → install)

工作流：完整安装流程（搜索 → 下载 → 安装）

bash

undefined

bash

undefined

1. Check AstroBox and list devices

1. 检查AstroBox状态并列出设备

npx astrobox-cli status npx astrobox-cli device list

2. If device is disconnected, get authkey from saved device and reconnect

2. 如果设备已断开连接，从已保存设备中获取authkey并重新连接

npx astrobox-cli device show <addr> # extracts authkey npx astrobox-cli device connect
--name "<name>" --addr "<addr>" --authkey "<key>"

npx astrobox-cli device show <addr> # 提取authkey npx astrobox-cli device connect
--name "<name>" --addr "<addr>" --authkey "<key>"

3. Search, download, and install the resource

3. 搜索、下载并安装资源

npx astrobox-cli provider refresh OfficialV2 npx astrobox-cli provider page OfficialV2 --keyword "<name>" --limit 20 npx astrobox-cli provider item OfficialV2 <id> # note the device key from Downloads npx astrobox-cli provider download OfficialV2
--id <id> --device <key>

npx astrobox-cli provider refresh OfficialV2 npx astrobox-cli provider page OfficialV2 --keyword "<name>" --limit 20 npx astrobox-cli provider item OfficialV2 <id> # 记录下载部分中的设备密钥 npx astrobox-cli provider download OfficialV2
--id <id> --device <key>

4. Download the file (url may need URL-encoding for spaces)

4. 下载文件（URL中的空格可能需要进行URL编码）

curl -L -o "resource.bin" "<download-url>"

5. Install through AstroBox

5. 通过AstroBox安装文件

npx astrobox-cli install "./resource.bin"

undefined

npx astrobox-cli install "./resource.bin"

undefined

Workflow: Check AstroBox health

工作流：检查AstroBox运行状态

bash

npx astrobox-cli status                               # should show "AstroBox: connected"

If it shows

unavailable

, tell the user to launch AstroBox first.

bash

npx astrobox-cli status                               # 应显示"AstroBox: connected"

如果显示

unavailable

，请告知用户先启动AstroBox。

Parsing output

输出解析

abcli outputs plain text, not JSON. Read

references/output-parsing.md

for field extraction patterns.

Key patterns:

Device lines:
```
- <name> (<addr>) [<status>]
```
Page items:
```
[<restype>] <name>\n  id: <id>
```
Provider download:
```
  <field>: <value>
```

abcli 输出纯文本，而非JSON格式。请查阅

references/output-parsing.md

获取字段提取规则。

关键规则：

设备行格式：
```
- <name> (<addr>) [<status>]
```
页码资源格式：
```
[<restype>] <name>\n  id: <id>
```
提供商下载信息格式：
```
  <field>: <value>
```

Important notes

重要注意事项

Always refresh before searching:
```
provider refresh <name>
```
before using
```
--keyword
```
, especially for OfficialV2. Provider caches can be stale.
Use
--keyword
for name searches: Do NOT pipe
```
provider page
```
through
```
grep
```
. Use the built-in
```
--keyword
```
flag.
Get authkey from
device show
: If a device is already saved but disconnected,
```
device show <addr>
```
reveals its authkey. No need to ask the user.
Device key comes from
provider item
: The
```
Downloads:
```
section lists device keys like
```
xmb9p
```
,
```
xmb10
```
,
```
xmrw5
```
. Use the correct one in
```
provider download --device <key>
```
.
Install returns "queued":
```
npx astrobox-cli install
```
outputs
```
{"ok": true, "message": "queued"}
```
. The actual transfer happens asynchronously. Check the device screen for progress.
npx concurrency: Running multiple
```
npx astrobox-cli
```
commands simultaneously can cause npm cache conflicts (
```
ENOTEMPTY
```
). If this happens, clear
```
~/.npm/_npx/*
```
and retry.

搜索前务必刷新：使用
```
--keyword
```
搜索前，先执行
```
provider refresh <name>
```
，尤其是针对OfficialV2提供商。提供商缓存可能已过期。
使用
--keyword
进行名称搜索：请勿通过管道将
```
provider page
```
的输出传递给
```
grep
```
，请使用内置的
```
--keyword
```
标志。
从
device show
获取authkey：如果设备已保存但断开连接，
```
device show <addr>
```
会显示其authkey，无需向用户索要。
设备密钥来自
provider item
：
```
Downloads:
```
部分会列出设备密钥，如
```
xmb9p
```
、
```
xmb10
```
、
```
xmrw5
```
。在
```
provider download --device <key>
```
中使用正确的密钥。
安装返回"queued"：
```
npx astrobox-cli install
```
会输出
```
{"ok": true, "message": "queued"}
```
。实际传输为异步进行，请查看设备屏幕了解进度。
npx并发问题：同时运行多个
```
npx astrobox-cli
```
命令可能导致npm缓存冲突（
```
ENOTEMPTY
```
）。若出现此问题，请清除
```
~/.npm/_npx/*
```
后重试。

Error handling

错误处理

Error	Meaning	Action
`Could not reach AstroBox...`	Desktop app not running	Ask user to launch AstroBox
`File does not exist: <path>`	Invalid install path	Verify path
`Device not found: <addr>`	Address not in list	Run `device list` first
`Invalid connectType: ...`	Wrong type	Only `SPP` or `BLE`

See

references/errors.md

for the full error catalog.

错误信息	含义	操作建议
`Could not reach AstroBox...`	桌面应用未运行	请用户启动AstroBox
`File does not exist: <path>`	安装路径无效	验证路径正确性
`Device not found: <addr>`	地址未在列表中	先运行 `device list`
`Invalid connectType: ...`	连接类型错误	仅支持 `SPP` 或 `BLE`

完整错误列表请查阅

references/errors.md

。

Command details

命令详情

For per-command usage, arguments, options, and output examples, read

references/commands.md

如需了解各命令的用法、参数、选项及输出示例，请查阅

references/commands.md

。

Reference index

参考索引

```
references/commands.md
```
— Full command reference
```
references/output-parsing.md
```
— Output format parsing guide
```
references/errors.md
```
— Error catalog and recovery steps

```
references/commands.md
```
— 完整命令参考
```
references/output-parsing.md
```
— 输出格式解析指南
```
references/errors.md
```
— 错误列表及恢复步骤