花生壳CLI

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

Features

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

Supported Platforms

Installation

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

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

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

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

Quick Start

1. 预下载客户端

hsk-cli download

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

# 上传单文件
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. 构建并部署项目

hsk-cli deploy

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

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

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

按 Ctrl+C 停止隧道。

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

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

Command Reference

Tunnel Management

tunnel — 启动内网穿透

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

tunnel list — 查看后台隧道

hsk-cli tunnel list

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

tunnel stop — 停止隧道

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

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

File Hosting

host — 文件托管

hsk-cli host <fileOrDirPath> [options]

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

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

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

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

Deploy

deploy — 构建并部署项目

hsk-cli deploy [options]

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

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

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

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

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

Task-Level API Key

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

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

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

# 保存 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 认领资源

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 资源（透传原生二进制）。

host-password — 管理访问口令

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）。

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

Authentication

auth — 账号认证

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

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

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

Capabilities

capabilities — 能力清单与版本门禁

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 — 本机引擎管理（安装 / 卸载 / 状态 / 日志 / 长期映射）

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 install / engine ensure 选项：

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

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

Supabase

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

hsk-cli supabase <action> [options]

在花生壳托管的静态站上接入 Supabase 数据库与登录。命令由 npm 包提供，独立 Go 二进制不注册该命令；能力与限制以运行时 hsk-cli supabase capabilities --format 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*（示例文件除外）不会进入部署包。

最小流程：

# 新用户先了解 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 — 检查资源状态

hsk-cli status [--json]

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

download — 预下载客户端

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

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

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 — 环境自检

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 — 显示平台信息

hsk-cli platform

Examples

启动内网穿透并管理

# 前台模式（按 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

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

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

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

任务级 API Key 认领（AI Agent）

# 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>

跨平台预下载

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

JSON 输出（AI 友好）

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

构建并部署

# 使用项目配置
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）

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

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

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

环境变量

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 for release history.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

License

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