HSK CLI

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

Features

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

Supported Platforms

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

Installation

Requirements: Node.js >= 14

# 全局安装
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

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 管理。

Global Options

| Option | Description | |--------|-------------| | --format <format> | 输出格式: json, pretty, table, ndjson, csv (默认: pretty) | | --dry-run | 预览模式，不执行实际操作 | | --json | --format json 的快捷方式 |

Command Reference

Tunnel Management

tunnel — 启动内网穿透

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 | 否 | 复用已有隧道，不存在则创建 | | --json | 否 | 以 JSON 格式输出 |

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 后上传。

| Option | Required | Description | |--------|----------|-------------| | <fileOrDirPath> | 是 | 本地文件或目录路径 | | --resource-id <id> | 否 | 资源 ID（传入则更新已有资源） | | --open | 否 | 上传完成后自动打开浏览器进行认领 | | --json | 否 | 以 JSON 格式输出 |

Deploy

deploy — 构建并部署项目

hsk-cli deploy [options]

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

| Option | Description | |--------|-------------| | --build-cmd <cmd> | 构建命令（默认: npm run build） | | --build-dir <dir> | 构建输出目录（默认: dist） | | --no-build | 跳过构建，直接上传现有目录 | | --resource-id <id> | 更新已有资源 | | --open | 上传完成后自动打开浏览器 | | --json | 以 JSON 格式输出 |

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

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

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

System

status — 检查资源状态

hsk-cli status [--json]

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

download — 预下载客户端

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

update — 更新客户端

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

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

跨平台预下载

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

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

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

# 更新已有资源
hsk-cli deploy --resource-id abc123 --open

Configuration

项目配置（package.json）

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

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

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

环境变量

| Variable | Description | Default | |----------|-------------|---------| | HSK_DOWNLOAD_URL | 客户端二进制下载基地址 | 从 versions.json 读取 | | HSK_FILE_HOSTING_API | Ticket API 完整 URL，覆盖原生二进制默认 host | 原生二进制内置默认值 |

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.