# @aweray/hsk-cli 中文文档

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

版本：0\.9\.15
npm 元数据更新时间：2026-10-30T08:17:16.527Z
中文译文更新时间：2026-11-07T08:51:55.353Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40aweray/hsk-cli
原文对照：https://npmcn.com/package/%40aweray/hsk-cli/?lang=original
项目主页：https://hsk.oray.com/

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

- 包体积（解压后）：531 kB，66 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- Node.js 要求：\>=16\.0\.0
- 运行依赖：3 个
- 首次发布：2026-06-29T09:32:01.872Z
- 最新版本发布：2026-10-30T08:17:16.337Z
- 近 30 天下载量：3211（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：19（近 12 个月 19 个）

## 中文简介

花生壳CLI - 内网穿透 & 文件托管，支持 Windows/macOS/Linux 多平台

## 安装

```sh
npm install @aweray/hsk-cli
```

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

## README

# 花生壳CLI

> 花生壳CLI — 零配置公网预览工具。一键内网穿透、文件托管，支持 Windows / macOS / Linux 多平台。

[![npm version](https://img.shields.io/npm/v/@aweray/hsk-cli)](https://www.npmjs.com/package/@aweray/hsk-cli) [![Node.js](https://img.shields.io/node/v/@aweray/hsk-cli)](https://nodejs.org/) [![License](https://img.shields.io/npm/l/@aweray/hsk-cli)](https://npmcn.com/package/%40aweray/hsk-cli/LICENSE)

## Features

-   **多平台自动适配** — 自动检测操作系统和架构，下载对应原生客户端二进制
-   **内网穿透** — 一键将本地服务暴露到公网，支持前台/后台两种保活模式
-   **文件托管** — 上传本地文件或目录（自动打包），获取公网下载链接
-   **构建部署** — `deploy` 命令一键完成 build → upload，原生二进制自动打包目录
-   **任务级 API Key** — `api-key` 保存/查看/清除 API Key，`file-hosting-bind` 凭 Key 自动认领资源
-   **资源复用** — 隧道支持 `--reuse` 检测，有效则复用，失效则重建
-   **AI 友好** — 支持 `--json` 结构化输出，便于 AI Agent 解析和自动化
-   **版本同步** — npm 包版本与原生二进制版本一致，自动匹配升级

## Supported Platforms

| Platform | Architectures |
| --- | --- |
| macOS | Intel (amd64), Apple Silicon (arm64) |
| Linux | amd64, arm64 |
| Windows | amd64 |

## Installation

**Requirements:** Node.js >= 16（硬下限，与 commander@11 对齐；推荐当前 LTS 18/20/22+）

```bash
# 全局安装
npm install -g @aweray/hsk-cli

# 或 npx 免安装运行
npx @aweray/hsk-cli <command>
```

首次运行时，CLI 会自动检测当前平台并下载对应的原生客户端二进制到 `~/.hsk/bin/`。

## Quick Start

### 1\. 预下载客户端

```bash
hsk-cli download
```

### 2\. 文件托管（上传文件或目录）

```bash
# 上传单文件
hsk-cli host ./document.pdf

# 上传目录（原生二进制自动打包为 zip）
hsk-cli host ./dist/

# 指定入口文件（目录无 index.html 时）
hsk-cli host ./dist/ --entry-file version.html

# 设置访问口令（8-16 位，需同时包含字母、数字和特殊字符；generate 由服务端随机生成 8 位）
hsk-cli host ./dist/ --set-password generate
```

> **访问口令**：不传 `--set-password` 时为公开访问；传了则访问者需输入口令。口令**不可读取，忘记只能重置**，请在输出中把口令转达/保存给用户。

### 3\. 构建并部署项目

```bash
hsk-cli deploy
```

自动执行 `npm run build` → 上传构建产物到文件托管。原生二进制自动打包目录。

### 4\. 启动内网穿透（前台保活）

```bash
hsk-cli tunnel --ip 127.0.0.1 --port 9000
```

按 `Ctrl+C` 停止隧道。

### 5\. 启动内网穿透（后台保活）

```bash
hsk-cli tunnel --ip 127.0.0.1 --port 9000 --detach
```

后台模式启动后 CLI 立即退出，隧道持续运行。使用 `tunnel list` / `tunnel stop` 管理。

> 注意：`--detach` 仅适用于已自动认领（登录 / api-key，claimed:true）的场景；匿名/需用户浏览器认领的隧道须前台运行等待认领回调（认领监听窗口默认 1800s，可用 `--timeout` 调整）。

* * *

## Global Options

| Option | Description |
| --- | --- |
| `--format <format>` | 输出格式: `json`, `pretty`, `table`, `ndjson`, `csv` (默认: `pretty`) |
| `--dry-run` | 预览模式，不执行实际操作（engine 幂等就绪/安装/卸载/映射写操作不支持，会返回 `DRY_RUN_UNSUPPORTED`） |
| `--json` | `--format json` 的快捷方式 |

* * *

## Command Reference

### Tunnel Management

#### `tunnel` — 启动内网穿透

```bash
hsk-cli tunnel --ip <IP> --port <PORT> [options]
```

| Option | Required | Description |
| --- | --- | --- |
| `--ip <ip>` | 是 | 本地服务 IP 地址 |
| `--port <port>` | 是 | 本地服务端口（1-65535） |
| `--arch <arch>` | 否 | 强制指定客户端架构: `win32`, `win64`, `macos-x64`, `macos-arm64`, `linux-x64`, `linux-arm64` |
| `--force-download` | 否 | 强制重新下载客户端二进制 |
| `--detach` | 否 | 后台模式，CLI 立即退出，隧道持续运行（仅自动认领场景；匿名认领须前台） |
| `--reuse` | 否 | 复用已有隧道，不存在则创建 |
| `--timeout <seconds>` | 否 | 匿名认领前台等待秒数（默认 120，上限 120，只影响认领等待，不影响隧道保活） |
| `--json` | 否 | 以 JSON 格式输出 |

#### `tunnel list` — 查看后台隧道

```bash
hsk-cli tunnel list
```

显示所有后台运行的隧道，包括 PID、本地目标、启动时间和日志路径。自动清理已停止隧道的残留记录。

#### `tunnel stop` — 停止隧道

```bash
# 停止指定 PID
hsk-cli tunnel stop --pid <PID>

# 停止全部
hsk-cli tunnel stop --all
```

### File Hosting

#### `host` — 文件托管

```bash
hsk-cli host <fileOrDirPath> [options]
```

支持上传单文件或目录。传入目录时，原生二进制自动打包为 zip 后上传。

**上传后自动认领**：上传成功后自动检测 API Key（`--api-key` 参数 > 本地配置 `~/.hsk/api_key.json`），有 Key 则自动执行 `file-hosting-bind` 认领：

-   认领成功 → 返回**真实资源链接**（资源页面，可直接访问，无需手动认领）
-   认领失败 / 无 Key → 返回**认领页面链接** + 手动认领提示

| Option | Required | Description |
| --- | --- | --- |
| `<fileOrDirPath>` | 是 | 本地文件或目录路径 |
| `--set-password <password>` | 否 | 访问口令（8-16 位，需同时包含字母、数字和特殊字符）或 `generate`（服务端随机生成 8 位）；不传则公开访问 |
| `--open` | 否 | 上传完成后自动打开浏览器进行认领（仅未自动认领时生效） |
| `--api-key <key>` | 否 | API Key（上传后自动认领，缺省从 `~/.hsk/api_key.json` 读取） |
| `--no-bind` | 否 | 跳过上传后自动认领，仅上传 |
| `--json` | 否 | 以 JSON 格式输出 |

> 注意：**不支持更新已有资源**（`--resource-id` 更新流程已下线）。每次执行 `host`/`file-hosting` 都会发布新资源（新 public\_url），内容更新请重新发布。

### Deploy

#### `deploy` — 构建并部署项目

```bash
hsk-cli deploy [options]
```

一键执行：**构建** → **上传** 到文件托管。原生二进制自动处理目录打包。

| Option | Description |
| --- | --- |
| `--build-cmd <cmd>` | 构建命令（默认: `npm run build`） |
| `--build-dir <dir>` | 构建输出目录（默认: `dist`） |
| `--set-password <password>` | 访问口令（8-16 位，需同时包含字母、数字和特殊字符）或 `generate`（服务端随机生成 8 位）；不传则公开访问 |
| `--no-build` | 跳过构建，直接上传现有目录 |
| `--open` | 上传完成后自动打开浏览器 |
| `--json` | 以 JSON 格式输出 |

> 注意：每次 `deploy` 都会发布新资源（不支持 `--resource-id` 更新已有资源）。

**配置优先级**: 命令行参数 > 项目 `package.json` 的 `hsk.deploy` > 全局 `~/.hsk/config.json` 的 `deploy` > 默认配置

**项目配置示例（`package.json`）**:

```json
{
  "scripts": {
    "build": "vite build"
  },
  "hsk": {
    "deploy": {
      "buildCmd": "npm run build",
      "buildDir": "dist"
    }
  }
}
```

### Task-Level API Key

#### `api-key` — 管理任务级 API Key 配置

```bash
hsk-cli api-key <set|get|clear> [options]
```

管理 `~/.hsk/api_key.json`（格式：`{"file_hosting": "<key>"}`，与原生二进制一致）。

| Option | Required | Description |
| --- | --- | --- |
| `<action>` | 是 | `set`（保存）/ `get`（查看）/ `clear`（清除） |
| `--scene <scene>` | 否 | 场景（默认: `file_hosting`） |
| `--key <key>` | set 时必填 | API Key（如 `ph_key_xxx`） |
| `--json` | 否 | 以 JSON 格式输出 |

```bash
# 保存 key
hsk-cli api-key set --scene file_hosting --key ph_key_xxx

# 查看 key
hsk-cli api-key get --scene file_hosting

# 清除 key
hsk-cli api-key clear --scene file_hosting
```

#### `file-hosting-bind` — 凭 API Key 认领资源

```bash
hsk-cli file-hosting-bind --resource-id <id> --verify_code <code> [options]
```

凭 API Key 调 `PUT /agent/ai-resource/file-hosting/:id/bind-owner` 认领已上传的 file-hosting 资源（透传原生二进制）。

| Option | Required | Description |
| --- | --- | --- |
| `--resource-id <id>` | 是 | 资源 ID（上传结果中的 `resource_id`） |
| `--verify_code <code>` | 是 | 验证码（上传结果中的 `verify_code`） |
| `--api-key <key>` | 否 | API Key，缺省从 `~/.hsk/api_key.json` 读取；传入时优先于配置文件 |
| `--json` | 否 | 以 JSON 格式输出 |

#### `host-password` — 管理访问口令

```bash
hsk-cli host-password --resource-id <id> --set-password <口令|generate> [--json]
hsk-cli host-password --resource-id <id> --remove-password [--json]

# 快捷写法 +hp（等价 host-password）
hsk-cli +hp --resource-id <id> --set-password generate
```

变更（设置 / 重置 / 取消）已发布资源的访问口令，透传原生二进制 `file-hosting-password`。口令**不可读取**，忘记只能重置（`--set-password generate`）。

| Option | Required | Description |
| --- | --- | --- |
| `--resource-id <id>` | 是 | 资源 ID（上传结果中的 `resource_id`） |
| `--set-password <password>` | 否 | 访问口令（8-16 位，需同时包含字母、数字和特殊字符）或 `generate`（服务端随机生成 8 位） |
| `--remove-password` | 否 | 取消访问口令（恢复公开访问）；与 `--set-password` 互斥 |
| `--json` | 否 | 以 JSON 格式输出 |

> 输出两态：`password` 非空 = 口令访问（**请妥善保存，忘记只能重置**）；`password` 为空串 = 公开访问。

### Authentication

#### `auth` — 账号认证

```bash
hsk-cli auth <login|status|logout> [options]
```

账号认证（login/status/logout）委托给原生二进制，凭据落盘 `~/.hsk/auth.json`。

| Option | Required | Description |
| --- | --- | --- |
| `<action>` | 否 | `login` / `status` / `logout`（默认 `status`） |
| `--method <method>` | 否 | 登录通道：`loopback` / `token` |
| `--token <token>` | 否 | 手动登录 token（`--method token` 通道） |
| `--no-wait` | 否 | loopback 下立即返回授权 URL，后台继续监听回调 |
| `--timeout <sec>` | 否 | 授权等待超时秒数 |
| `--json` | 否 | 以 JSON 格式输出 |

`auth status` 输出 `authenticated` 布尔值及 `status`（`authenticated` / `pending_callback` / `pending_device` / `pending_claim` / `none`）。

### Capabilities

#### `capabilities` — 能力清单与版本门禁

```bash
hsk-cli capabilities --format json
```

输出 `{schema_version, version, updated, commands[], features{}}`。`features` 为稳定能力位（如 `engine.ensure` / `engine.mapping.create` / `engine.mapping.wait_ready`）。

能力门禁：官网文档页头声明 `min_cli_version`；`doctor` 会执行 `capabilities --format json` 并比对必备能力位，缺失/旧版本返回 `fail` + 升级命令（不自动升级）。agent 也可手动自检，缺失时先升级再按文档执行。

### Engine

#### `engine` — 本机引擎管理（安装 / 卸载 / 状态 / 日志 / 长期映射）

```bash
hsk-cli engine ensure [--method loopback|token] [--timeout <s>] [--installer <path>] [--elevation available] [--format json]   # 幂等就绪
hsk-cli engine install [options]                     # 系统级安装（默认子命令，缺省 action 即 install）
hsk-cli engine status [--format json]                # 引擎/节点/映射状态
hsk-cli engine uninstall [--format json]             # 卸载本机引擎（幂等）
hsk-cli engine logs [-n 100] [-level <level>] [--format json]   # 引擎日志（tail）
hsk-cli engine mapping create -ip <ip> -port <port> [-protocol https|http|tcp] [-name <name>] [-license-id <id>] [-wait-ready 60] [--format json]
hsk-cli engine mapping list [--format json]          # 列出本机节点的长期映射
hsk-cli engine mapping delete <id> [--format json]   # 删除长期映射（先查后删两阶段）
```

管理 hsk-ng 本机引擎（长期隧道的保活载体）：`ensure` 幂等就绪（未装则装、未运行则启、节点丢失则重注册；已就绪零写）、`install` 系统级安装、`status` 引擎/节点/映射状态、`uninstall` 卸载（幂等：未安装视为已达成）、`logs` 引擎日志、`mapping create|list|delete` 长期映射增删查。命令委托给原生二进制（Go 侧状态机 S0~S10）：逐步 JSON 输出到 stderr，最终 Result 到 stdout。**安装/卸载需已登录**（未登录自动引导 `hsk-cli auth login`，取消/未完成 → `AUTH_CANCELLED`，退出码 4）；系统级安装直接执行、不再需要额外确认，权限不足时输出 needs\_input 交接载荷。**Windows 提权不可用时必须以管理员终端重跑 `hsk-cli engine install --elevation available`，禁止直接运行 `OrayHskNGInstaller.exe`**：安装 token（S4 自动换取）与 `--api`（beta 包为 oraybeta 域）只由 CLI 注入，直接运行安装包会以 `--token "$EXEFILE"` 注册失败（exit 2）并回落生产 api。

`engine ensure` 输出 `{ready, engine_version, node_id, node_status, blockers[]}`；**ready=true 才继续建映射**。未登录 → `AUTH_CANCELLED`（先 `hsk-cli auth login`）；需提权 → `ELEVATION_REQUIRED` + 可复制命令；已就绪只读返回、不做写操作。

`engine mapping create` 的 **`-protocol` 默认 `https`**：内网服务为 http 时可用 `https`/`http`（默认 `https`）；内网服务为 https 或非 http（含裸 TCP）时只能传 `tcp`。由 agent 按用户意图显式传 `-protocol`，CLI 不做协议探测（仅在创建时做一次 TCP 可达性探测用于告警，不阻塞）。同一 `ip:port` 的不同 `protocol` 视为不同映射、不会复用；如需复用历史 `tcp` 映射，请显式传 `-protocol tcp`。

参数校验：`-ip` 支持 IP 或主机名；`-name` 最长 128；JSON 错误含 `error_code/retryable/fix_hint/fix_command/next_actions/field`，参数错误按 `field` 定位。

`-wait-ready N`（N>0）会在创建/复用后轮询映射到 `active`，并做端到端自证（http/https GET `public_url`，tcp dial `public host:port`），输出 `ready/selfcheck/next_actions`；`ready=true` 才视为成功。**自证判定**：2xx/3xx、tcp 连通、非 `404` 的 4xx（如 401/403/405）立即视为可达；`404/408/429` 属「待定」，会在窗口内持续探测，连续稳定 ≥3 秒仍为 4xx 才判定源站可达并附 `selfcheck.note` —— 避免创建瞬间数据面路由尚未下发时的网关 404 被误判为就绪；5xx/网络错误继续重试。

**网关错误页识别**：网关兜底/错误页统一带 `X-Hsk-Edge-Error` 响应头（`RESOURCE_NOT_FOUND`/`RESOURCE_BANNED`/`TUNNEL_NOT_ACTIVE`/`TARGET_*` 等），自证见该头即判「请求未到达源站」，**永不判 `ready`**（不参与 4xx 稳定判定），超时 `selfcheck.error` 给出可操作归因、`selfcheck.edge_error` 输出原始错误码；旧版网关无该头时退化为 4xx 稳定判定。超时返回 `ready=false`（映射已创建，勿重复创建），`selfcheck` 输出 `http_status/attempts/first_http_status/settled_ms/error`，按 `next_actions` 用 `engine logs` / `engine status` 排障。

**服务未运行（`SERVICE_REGISTER_FAILED`）**：`engine mapping create` 报该码通常不是创建失败，而是引擎已装但系统服务未运行（`engine status --format json` 的 `service_running=no`），映射不会生效。先 `engine status` 确认，再重跑 `engine install` 或启动系统服务（Windows 服务名 `OrayHskNG`）。Windows 全新安装由安装器自动注册并启动；仅覆盖安装/升级时安装器可能先停旧服务但未拉起，CLI 才在 S8 用 `sc start OrayHskNG` 兜底；`sc.exe` 不可用/权限不足时兜底失败，S9 仍报 `SERVICE_REGISTER_FAILED`，需以管理员执行 `sc start OrayHskNG` 或重跑 `engine install`。

**`--dry-run` 边界**：engine 的 `ensure` / `install` / `uninstall` / `mapping create` / `mapping delete` 不支持 `--dry-run`；传入会返回 `DRY_RUN_UNSUPPORTED` 并阻止执行（不会真实安装/删除）。只读查询用 `engine status` / `engine logs` / `engine mapping list`。

子命令参数在 npm 壳层原样透传给原生二进制（含多位置参数与单横线 flag，如 `-ip` / `-port` / `-protocol` / `-name` / `-license-id` / `-n` / `-level`）。

| 子命令 | 说明 |
| --- | --- |
| `engine ensure [options]` | 幂等就绪：未装则装、未运行则启、节点丢失则重注册；输出 `ready/blockers` |
| `engine install [options]` | 系统级安装本机引擎（需登录） |
| `engine status` | 引擎/节点/映射状态（含 `mappings[]` 明细；本地字段尽力输出，远端失败为 `unknown`） |
| `engine uninstall` | 卸载本机引擎（幂等；活跃映射数会如实披露） |
| `engine logs [-n 100] [-level <level>]` | 查看引擎日志（tail，默认 100 行，`-level` 过滤） |
| \`engine mapping create -ip -port \[-protocol https | http |
| `engine mapping list` | 列出本机节点的长期映射 |
| `engine mapping delete <id>` | 删除长期映射（先查后删两阶段） |

`engine install` / `engine ensure` 选项：

| Option | Required | Description |
| --- | --- | --- |
| `--version <ver>` | 否 | 显式指定客户端版本（默认 client-versions 最新） |
| `--method <method>` | 否 | 登录通道：`loopback` / `token`（未登录时生效） |
| `--timeout <sec>` | 否 | 登录等待超时秒数（透传） |
| `--installer <path>` | 否 | 离线安装包路径（跳过下载，仍做 sha256 校验） |
| `--api <url>` | 否 | 覆盖控制台 API 基址（仅本次安装流程生效） |
| `--elevation <level>` | 否 | `available` 表示已以特权运行（跳过提权探测） |
| `--yes` | 否 | **已废弃**（兼容保留，无效果）：安装已无确认步骤，老脚本传该参数不报错 |

通用选项：`--json`（等同于 `--format json`）。

退出码：`0` 成功；`1` 通用错误；`4` 认证类错误（如未登录的 `AUTH_CANCELLED`）。

### Supabase

#### `supabase` — 静态站接入 Supabase Cloud（npm-only）

```bash
hsk-cli supabase <action> [options]
```

在花生壳托管的静态站上接入 Supabase 数据库与登录。命令由 npm 包提供，**独立 Go 二进制不注册该命令**；能力与限制以运行时 `hsk-cli supabase capabilities --format json` 为准，本节不维护第二份列表。

| `<action>` | 说明 |
| --- | --- |
| `capabilities` | 输出业务能力、限制与命令分层（离线可用） |
| `guide` | 新用户 PAT 引导：PAT 是什么、如何注册账号并创建 PAT（离线可用） |
| `template` | 输出最小站点骨架（仅打印，不落盘） |
| `status` | 查看本地关联与未决操作（不读取凭据） |
| `setup` | 建/关联项目 → 收敛 schema/RLS → 生成前端配置（需 `--yes`） |
| `link` | 关联已有项目，不执行 DDL（需 `--yes`） |
| `sync` | 精确同步 Auth 回调与 site\_url，`--domain <public_url>` 必填（需 `--yes`） |
| `login` / `logout` | 管理 OS 钥匙串中的 PAT（需 `--yes`） |
| `open` | 打开该项目控制台 |

| Option | Required | Description |
| --- | --- | --- |
| `--project-dir <dir>` | 否 | 站点根目录（含 `hsk.supabase.json`；默认从 cwd 向上查找） |
| `--organization <slug>` | 否 | 目标组织 slug（多组织必填） |
| `--project-ref <ref>` | 否 | 已有项目 ref（`link` 必填） |
| `--domain <url>` | 否 | 本站点部署 URL（`sync` 必填） |
| `--yes` | 否 | 显式确认后才读取凭据并调用远端 |
| `--dry-run` | 否 | 纯本地预览：不读钥匙串、不联网、不落盘 |
| `--format json` | 否 | 以 JSON 格式输出 |

**写执行门**：`login`/`logout`/`setup`/`link`/`sync` 未加 `--yes` 时返回 `SUPABASE_EXECUTION_NOT_READY`，不读取凭据、不调用远端。

**红线**：**数据出境**——动态数据（含访客提交的表单 / 账号信息）存储在境外 Supabase，`setup` 首次执行会先打印合规提示并需 `--yes` 确认；前端只使用 `sb_publishable_*` key，secret key 绝不进入前端或部署包；PAT 继承账号全部权限（可创建/删除该账号下的任意项目），首次 `login` 会提示风险，生成物与日志永不回显 PAT；每次部署后需精确同步 Auth 回调（共享根域禁用通配回调）；SMTP 仅在需要发信（邮箱确认 / 魔法链接 / 邮件 OTP / 找回密码）时强制，远端已关闭邮箱确认的纯密码登录不强制。`.hsk/` 状态目录与 `.env*`（示例文件除外）不会进入部署包。

最小流程：

```bash
# 新用户先了解 PAT（可随时复查）：
hsk-cli supabase guide          # PAT 是什么 → 注册 Supabase 账号（https://supabase.com/dashboard/sign-up）
                                # → 创建 PAT（https://supabase.com/dashboard/account/tokens）

# 站点根目录放置 hsk.supabase.json 声明
hsk-cli supabase login --yes   # 交互式隐藏输入 PAT（非交互环境由凭据系统注入 SUPABASE_ACCESS_TOKEN 或经 stdin，勿在命令/脚本中明文写入）
hsk-cli supabase setup --yes
hsk-cli deploy
hsk-cli supabase sync --domain <public_url> --yes
```

### System

#### `status` — 检查资源状态

```bash
hsk-cli status [--json]
```

检查已发布的隧道资源状态（进程存活 + URL 可访问）。

#### `download` — 预下载客户端

```bash
hsk-cli download [--arch <arch>]
```

#### `update` — 升级 npm 包并同步客户端二进制

```bash
hsk-cli update [--arch <arch>] [--force]
```

全局安装时若 registry 有新版，会执行 `npm i -g @aweray/hsk-cli@latest --no-audit --no-fund`（POSIX 附带清空 HTTP\_PROXY 前缀，Windows 直接给可执行命令），然后从**磁盘上的新包**重读 `versions.json` 再下载二进制，并自动重生成 `~/.hsk/AGENTS.md`、只刷新**已注册**的 skill 副本（不扩未装智能体）。若 PATH 上还有其它全局前缀的 `hsk-cli`，会打印对应 PATH 前置的 `npm i -g` 指引。

长期默认 vs 临时映射：机器级 `persistence=long_term` 时，创建映射默认走 `engine ensure` + `engine mapping create`（长期）；仅当本次明确只需临时映射时，显式传 `--context persistence=temporary` 再执行 `tunnel`。`tunnel` 输出含 `mode=temporary` 与 `expires_at`，到期自动失效。

安装卫生：`hsk-cli doctor --fix` 会清理失效 shim，并把 npm 全局 bin 写入 PATH（新终端生效）；若仍提示旧包 shim 冲突，确认不再使用后先 `npm uninstall -g @aweray/hsk-cli`（或 `@aweraydev/hsk-cli`）再重装。

npx 运行不会执行 `npm i -g`，会打印 `npx -y @aweray/hsk-cli@latest` 指引。

#### `doctor` — 环境自检

```bash
hsk-cli doctor [--fix] [--format json]
```

检查 Node 版本、PATH、`~/.hsk` 可写、二进制、AGENTS.md、skill 注册、连通性、npm 包是否最新。`--fix` 只做本地修复（`download` / 重生成 AGENTS.md / 刷新已注册的 skill 副本，并补注册缺失副本），**不会**执行 `npm i -g`，也不会为未安装的智能体新建配置根。skill 单独刷新可用 `hsk-cli skill --refresh`（只更新已注册副本），补注册用 `hsk-cli skill --register-all`。

#### `platform` — 显示平台信息

```bash
hsk-cli platform
```

* * *

## Examples

### 启动内网穿透并管理

```bash
# 前台模式（按 Ctrl+C 停止）
hsk-cli tunnel --ip 127.0.0.1 --port 9000

# 后台模式
hsk-cli tunnel --ip 127.0.0.1 --port 9000 --detach

# 查看后台隧道
hsk-cli tunnel list

# 停止全部后台隧道
hsk-cli tunnel stop --all

# 复用已有隧道（有效则复用，失效则重建）
hsk-cli tunnel --ip 127.0.0.1 --port 9000 --reuse
```

### 上传文件或目录并自动认领

```bash
# 上传单文件
hsk-cli host ./report.pdf --open

# 上传目录（原生二进制自动打包为 zip）
hsk-cli host ./dist/ --open
```

### 任务级 API Key 认领（AI Agent）

```bash
# 1. 上传资源，记录输出中的 resource_id 与 verify_code
hsk-cli host ./dist/ --format json

# 2. 保存 API Key
hsk-cli api-key set --scene file_hosting --key ph_key_xxx

# 3. 认领资源（也可直接传 --api-key <key>，参数优先于配置文件）
hsk-cli file-hosting-bind --resource-id <id> --verify_code <code>
```

### 跨平台预下载

```bash
# 在 macOS 上预下载 Linux 版本
hsk-cli download --arch linux-x64
```

### JSON 输出（AI 友好）

```bash
hsk-cli tunnel --ip 127.0.0.1 --port 9000 --json
hsk-cli host ./document.pdf --json
hsk-cli status --json
hsk-cli api-key get --scene file_hosting --json
hsk-cli file-hosting-bind --resource-id <id> --verify_code <code> --json
```

### 构建并部署

```bash
# 使用项目配置
hsk-cli deploy

# 命令行覆盖配置
hsk-cli deploy --build-cmd "yarn build" --build-dir "build"

# 跳过构建，直接上传现有目录
hsk-cli deploy --no-build

# 重新发布（不支持更新已有资源，每次发布生成新资源/新链接）
hsk-cli deploy --open
```

* * *

## Configuration

### 项目配置（`package.json`）

```json
{
  "hsk": {
    "deploy": {
      "buildCmd": "npm run build",
      "buildDir": "dist"
    }
  }
}
```

### 全局配置（`~/.hsk/config.json`）

```json
{
  "deploy": {
    "buildCmd": "npm run build",
    "buildDir": "dist"
  }
}
```

### 环境变量

| Variable | Description | Default |
| --- | --- | --- |
| `HSK_CLI_DOWNLOAD_BASE` | 覆盖二进制下载基地址（联调内网包用，无需改 `versions.json` 再发版） | `versions.json` 的 `downloadBaseUrl`（线上 `https://dw.oray.com/onion/cli`） |
| `HSK_FILE_HOSTING_API` | Ticket API 完整 URL，覆盖原生二进制默认 host | 原生二进制内置默认值 |
| `HSK_NO_UPDATE_CHECK` | 设为 `1` 时禁用启动时的 npm 包更新检测 | 未设置 |
| `HSK_UPDATE_CHECK_INTERVAL_HOURS` | 更新检测缓存新鲜度（小时） | `24` |
| `HSK_NPM_REGISTRY` | 覆盖 npm registry（否则读 `npm_config_registry`，后台 worker 再回退 `npm config get registry`） | `https://registry.npmjs.org` |

* * *

## Logs

-   **macOS / Linux**: `~/.hsk/logs/`
-   **Windows**: `%USERPROFILE%\.hsk\logs\`

* * *

## How It Works

```
┌─────────────────┐     ┌──────────────┐     ┌─────────────────┐
│   hsk-cli npm   │ ──▶ │  versions.json │ ──▶ │  download binary  │
│   package (node)│     │  (version map) │     │  ~/.hsk/bin/    │
└─────────────────┘     └──────────────┘     └─────────────────┘
         │
         ▼
┌─────────────────┐
│  native binary  │  ← 实际执行内网穿透/文件托管
│  (cross-platform)│
└─────────────────┘
```

-   **npm 包**（启动器）：提供命令行接口、平台检测、自动下载、版本管理、资源状态持久化
-   **versions.json**：定义 npm 包版本与原生二进制版本的映射关系
-   **原生二进制**：按平台编译（Go/Rust/C++），实际执行网络穿透和文件传输
-   **资源状态**：保存在 `{projectRoot}/.hsk/resources.json` 或 `~/.hsk/resources.json`

* * *

## Notes

-   During installation, the package automatically downloads the appropriate native binary for your operating system and architecture.
-   The CLI caches downloaded binaries in `~/.hsk/bin/`. No manual setup is required after installation.
-   The npm package version and native binary version are kept in sync. When you update the npm package, the corresponding binary will be downloaded automatically.
-   **前台模式（默认）**: CLI 启动客户端二进制作为子进程，实时输出日志，捕获到公网地址后持续运行。按 `Ctrl+C` 发送 `SIGTERM` 优雅停止。
-   **后台模式（`--detach`）**: CLI 启动子进程后使用 `detached: true` 解除父子绑定，立即退出。子进程在后台独立运行，日志写入 `~/.hsk/logs/`，PID 记录保存到 `~/.hsk/pids/`.
-   **Deploy**: `hsk-cli deploy` 执行 `build` → `upload` 两步。原生二进制自动打包目录，无需额外依赖.
-   **File Hosting**: `hsk-cli host` 支持单文件和目录上传。传入目录时，原生二进制自动打包为 zip.
-   **资源复用**: `hsk-cli tunnel --reuse` 先检测已有隧道（进程存活 + URL 可访问），有效则复用，失效则重新创建.
-   Enable `--dry-run` to preview operations without executing them.

* * *

## Changelog

See [CHANGELOG.md](https://npmcn.com/package/%40aweray/hsk-cli/CHANGELOG.md) for release history.

## Contributing

We welcome contributions! Please see [CONTRIBUTING.md](https://npmcn.com/package/%40aweray/hsk-cli/CONTRIBUTING.md) for guidelines.

## License

Copyright (c) 2026 Oray Inc. All rights reserved.

## 常见问题

### @aweray/hsk-cli 是什么？

花生壳CLI - 内网穿透 & 文件托管，支持 Windows/macOS/Linux 多平台

### 如何安装 @aweray/hsk-cli？

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

### @aweray/hsk-cli 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/aweray\_\_hsk-cli 是否存在。

### @aweray/hsk-cli 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

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

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

### @aweray/hsk-cli 可以商用吗？

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

### @aweray/hsk-cli 的下载量有多少？

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

### @aweray/hsk-cli 还在维护吗？

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