Hatch CLI

Hatch CLI (hatch) 是 Hatch 部署平台的官方命令行工具，供开发者、CI/CD 流水线以及 AI Coding Agent 发布应用、切换分享版本、签发通行证。

1. 环境前置要求

• Node.js >= 20
• 网络可连通 Hatch 服务的 API 地址（如 http://localhost:3000 或私有部署域名）

2. 安装与配置步骤

2.1 安装方式

根据您的使用场景，选择以下方式之一：

方式 A：通过 npm 官方源一键安装（推荐，生产环境/CI首选）

无需拉取源码，直接从 npm 全局安装：

npm install -g @meshinfo/hatch@^0.2.0
# 或者使用 pnpm / yarn / bun
pnpm add -g @meshinfo/hatch@^0.2.0

# 也可以直接免安装通过 npx 执行：
npx @meshinfo/hatch@^0.2.0 --help
hatch --version   # 必须 ≥ 0.2.0；0.1.0 仍是 --env / rollback 旧模型

方式 B：当前源码仓库全局软链接（本地开发使用）

在项目根目录下编译并软链接到系统 PATH：

# 1. 编译 CLI
npm run cli:build

# 2. 软链接到系统路径（以 /usr/local/bin 为例）
sudo ln -sf "$(pwd)/packages/cli/dist/hatch.js" /usr/local/bin/hatch

# 3. 验证是否安装成功
hatch --help

方式 C：本地/跨机全局安装

将本包作为全局模块安装：

npm install -g ./packages/cli

方式 D：免安装直接运行（仅限仓库内）

无需全局安装，在仓库根目录直接运行：

npx hatch --help
# 或者
npm run hatch -- --help

3. 安装后设置（认证配置）

CLI 需要获得 Hatch 控制面的 API 地址 与 API Key 访问令牌。

第 1 步：获取 API Key

1. 打开浏览器登录 Hatch Web 控制台（如 http://localhost:3000）。
2. 点击右上角导航栏进入 【Settings】 -> 【API Keys】。
3. 点击 Create API Key，输入 Key 名称（例如 my-laptop-cli），勾选 read、deploy、runtime，需要建应用再加 write:projects。
4. 复制生成的 Key 字符串（格式如 hatch_live_xxx...，只展示一次，请妥善保存）。

第 2 步：配置认证（二选一）

选项 1：执行 hatch login（推荐本地开发者，一次配置长期有效）

hatch login --url http://localhost:3000

终端会提示：

API key: <粘贴刚才复制的 key，终端会自动隐式输入>

或者使用一键免交互管道命令（适合脚本自动化）：

echo "hatch_live_xxx..." | hatch login --url http://localhost:3000 --token-stdin

[!NOTE] 凭据会自动加密保存在用户主目录的 ~/.config/hatch/config.json（文件权限为 0600）。

选项 2：环境变量注入（推荐 CI/CD、Docker、AI Agent）

无需执行 hatch login，直接设置环境变量（优先级高于配置文件）：

export HATCH_API_URL="http://localhost:3000"
export HATCH_API_KEY="hatch_live_xxx..."

第 3 步：验证配置

运行 hatch whoami 验证连通性：

hatch whoami

成功后会返回当前登录的邮箱、所在团队列表以及 API Key 的 Scope 权限。

4. 常用命令清单

项目与团队

# 列出所在团队
hatch teams ls

# 列出所有项目（支持 --json 格式化输出）
hatch projects ls [--team <teamId>] [--json]

# 创建新项目
hatch projects create --team <teamId> --name "my-app" [--description "..."]

# 查询指定项目详情（支持 ID 或 Slug）
hatch projects get <id|slug>

应用部署与生命周期

# 部署单页应用 / 静态站点（支持 zip 或单个 html）。默认成为正在分享的版本。
hatch deploy dist.zip --project my-app [--preview] [--keep] [--profile A|B] [--image-ref registry/img:tag]

# 检查 zip（本地 + 按项目 Origin 能力）
hatch preflight dist.zip --project my-app
hatch doctor

# 先预览、再给大家看这个版本。恢复历史版本且两槽都在线时：
# --evict preview（默认）顶掉预览；--evict shared 保留预览、替换正在分享的版本
hatch share <version> --project my-app
hatch share <version> --project my-app --evict preview
hatch share <version> --project my-app --evict shared

# 查看项目的所有部署历史与实时状态
hatch deploys ls --project <id|slug>

# 查看某次具体部署详情
hatch deploys get <deployId>

# 暂停 / 恢复某次部署
hatch pause <deployId>
hatch resume <deployId>

# 给团队外的人发通行证（默认 7 天）
hatch token create --project my-app [--ttl 7d] [--label reviewer]
hatch token list --project my-app
hatch token revoke <tokenId> --project my-app

API Key 管理

hatch keys ls
hatch keys create --name "agent-key" --scope read,deploy,runtime,write:projects
hatch keys revoke <keyId>

登出

hatch logout