CLI 参考（高频精要）

本文为速查参考手册。概念性文档请参阅：

提示：大多数命令均支持 --help 和 --json。

核心命令

初始化（源码安装）：hstack setup-from-source --profile=dev|selfhost（已弃用的别名：hstack setup）
运行：hstack start / hstack dev
交互式运行器（推荐）：hstack tui <...>（示例：hstack tui stack dev dev --mobile）
停止：hstack stop
诊断：hstack where、hstack doctor、hstack logs
参与贡献：hstack contrib status|ensure-dev|sync|extract|pr

常用运行标志（根命令）：

--server=Kaiwu-server|Kaiwu-server-light
--restart
--no-ui、--no-daemon
--no-browser
--mobile
--expo-tailscale
--bind=loopback|lan（别名：--loopback、--lan）

远程开发目标：

添加：hstack dev-targets add ⟦K4⟧ --platform=posix|windows --ssh=⟦K5⟧ --repo-dir=⟦K6⟧ --cli-home-dir=⟦K7⟧ [--ssh-config-file=⟦K8⟧] [--stack=⟦K9⟧]
查看：hstack dev-targets list|path [--stack=⟦K10⟧]、hstack dev-targets show ⟦K11⟧ [--stack=⟦K12⟧]
预检：hstack dev-targets doctor [name] [--stack=⟦K13⟧]
移除：hstack dev-targets remove ⟦K14⟧ [--stack=⟦K15⟧]

参阅：远程开发目标。

栈

生命周期：

创建：hstack stack new ⟦K16⟧ [--interactive] [--db-provider=pglite|sqlite|postgres|mysql] [--database-url=⟦K17⟧]
编辑：hstack stack edit ⟦K18⟧ --interactive
列表/信息：hstack stack list、hstack stack info ⟦K19⟧
运行：hstack stack dev ⟦K20⟧、hstack stack start ⟦K21⟧
停止：hstack stack stop ⟦K22⟧
构建：hstack stack build ⟦K23⟧、hstack stack build ⟦K24⟧ --web|--server|--daemon|--all、hstack stack build ⟦K25⟧ --activate-runtime
- --tauri 仍为传统的本地 hstack build 标志，并非 v1 中具名栈的产物或运行时目标。
基于现有产物激活运行时：hstack stack runtime ⟦K26⟧ activate --web|--server|--daemon|--all
诊断：hstack stack doctor ⟦K27⟧

将栈绑定至工作树/检出目录：

hstack stack wt ⟦K28⟧ -- use ⟦K29⟧

服务端变体：

hstack stack srv ⟦K30⟧ -- use Kaiwu-server-light|Kaiwu-server

认证：

hstack auth seed（创建 dev-auth 种子栈）
hstack stack auth ⟦K31⟧ status|login|copy-from

栈作用域应用 CLI（在栈上下文中运行 Kaiwu CLI/守护进程）：

hstack stack Kaiwu ⟦K32⟧ -- <args...>

服务：

hstack stack service ⟦K33⟧ install|enable|status|restart|logs|tail

菜单栏：

hstack menubar install --stack=⟦K34⟧ --mode=selfhost

类生产环境的具名栈典型工作流：

hstack stack new dev-built --repo=/absolute/path/to/checkout
hstack stack build dev-built --activate-runtime
hstack stack env dev-built set Kaiwu_STACK_RUNTIME_MODE=prefer
hstack stack service dev-built install
hstack stack service dev-built enable
hstack menubar install --stack=dev-built --mode=selfhost

仅组件级运行时刷新：

# UI-only refresh
hstack stack build dev-built --web
hstack stack runtime dev-built activate --web

# Server-only refresh
hstack stack build dev-built --server
hstack stack runtime dev-built activate --server
hstack stack service dev-built restart

PR 栈：

hstack stack pr ⟦K35⟧ --repo=<pr-url|number> [--dev|--start] [--server-flavor=light|full] [--db-provider=...] [--database-url=...]

移动端 (iOS)

安装共享 dev-client 应用（USB 连接 iPhone）：hstack mobile-dev-client --install
安装单栈独立应用（Release 模式，不依赖 Metro）：hstack stack mobile:install ⟦K36⟧ [--device=...] [--name=...]
重新生成原生工程（Pods、部署目标补丁）：hstack mobile --prebuild [--clean]

参阅：移动端 (iOS)。

EAS (Expo Application Services)

EAS 封装命令（在 apps/ui 中运行 EAS CLI，尽可能确保依赖已安装）：

云端构建：hstack stack eas ⟦K37⟧ ios|android [--profile production] [--interactive|--non-interactive]
参数透传：hstack stack eas ⟦K38⟧ ⟦K39⟧

同步栈环境变量至 EAS 环境变量控制台（项目设置）：

hstack stack eas ⟦K40⟧ env:sync --environment production [--dry-run] [--hide-values]

参阅：移动端 (iOS)（各栈独立的 EAS 构建）。

工作树 (`wt`)

创建工作树（默认为基于 upstream 的本地工作树）：

hstack wt new local/⟦K41⟧ [--from=upstream|origin] [--base=⟦K42⟧] [--use]

PR 工作树：

hstack wt pr <pr-url|number> [--use] [--update] [--stash]

选择当前生效的代码检出目录：

hstack wt use ⟦K43⟧

状态/列表/更新：

hstack wt status ⟦K44⟧
hstack wt list
hstack wt update ⟦K45⟧
hstack wt update-all

推送：

hstack wt push <spec|active> --remote=origin

认证

hstack auth seed
hstack auth copy-from ⟦K46⟧ --all --except=main,dev-auth
hstack auth dev-key --print

参阅：认证（dev-auth 播种）。

提供商

列出支持的提供商 CLI 以及当前平台是否支持自动安装：

hstack providers list

安装提供商 CLI（尽可能自动安装）：

hstack providers install claude,codex,gemini
hstack providers install claude codex gemini

常用标志：

--dry-run / --plan（预览即将执行的操作）
--force / --reinstall（即便已安装也重新运行安装程序）
--json（脚本自动化调用）

另请参阅：编码智能体。

远程配置

通过 SSH 初始化远程设备（安装 Kaiwu、配对凭据，并可选择安装/启动守护进程服务）：

hstack remote daemon setup --ssh user@host [--channel stable|preview|dev] [--service user|none]

通过 SSH 初始化远程设备，以托管服务形式运行自托管服务端：

hstack remote server setup --ssh user@host [--channel stable|preview|dev] [--mode user|system] [--env KEY=VALUE]...

参阅：

自托管运行时 (`self-host`)

以托管服务形式安装并管理自托管运行时（服务端 + 可选 Web UI 资源包）：

安装：hstack self-host install [--channel stable|preview|dev] [--mode user|system]
状态：hstack self-host status
手动更新：hstack self-host update
回滚：hstack self-host rollback --to ⟦K47⟧

自动更新计划（需手动启用）：

启用每日更新窗口：hstack self-host install --auto-update --auto-update-at=03:15
安装后更改调度计划：hstack self-host config set --auto-update --auto-update-at=03:15

配置查看与微调：

查看：hstack self-host config view
设置（并应用调度变更）：hstack self-host config set ...
设置（仅写入配置）：hstack self-host config set ... --no-apply

贡献者工作流 (`contrib`)

以下命令可助你在长期维护的 dev/ 检出目录下工作，同时生成干净规范的 PR 分支：

确保 dev/ 存在：hstack contrib ensure-dev
同步 dev/：hstack contrib sync
提取特性分支：hstack contrib extract ⟦K48⟧ --mode=reset|stack [--push] [--open]
输出/打开 PR 链接：hstack contrib pr ⟦K49⟧ [--open]

维护者工具

hstack 将一系列“维护者工具”作为子命令提供（setup-pr、review-pr、import、review、edison）：

hstack tools --help

单体仓库迁移

hstack monorepo port --help

参阅：单体仓库迁移（旧版拆分仓库）。

CLI 参考（高频精要）

On this page