CLI 总览

@steamharness/cli 只暴露一个 steamharness 命令，并按用途分为两个命令组：

命令组	用途
steamharness	在本地 workflow 目录运行、输出 JSON 报告、检查结构，或启动 stdio MCP Server。
steamharness workspace / pnpm exec steamharness workspace	连接 SteamHarness Server，完成登录、打包、上传、发布、下载和版本查询。

命令索引

CLI	命令
steamharness	run、json、structure、resolve-params、mcp、help
workspace	login、logout、status、health、pack、upload、publish、versions、download、help

典型工作流

本地开发时，先用 steamharness 在 workflow 目录验证运行结果和结构，再用 workspace CLI 上传到 server。

steamharness run workspace/workflow/hello -- --message "hello"
steamharness json workspace/workflow/hello -- --message "hello"
steamharness structure workspace/workflow/hello
steamharness mcp workspace/workflow/hello
steamharness json workspace/workflow/runtime-timer -- --title "Fixture Timer" --milliseconds 2000

发布到 server 时，先检查服务状态，再登录、上传、发布和下载。

pnpm exec steamharness workspace health --server http://localhost:7126
pnpm exec steamharness workspace login --server http://localhost:7126
pnpm exec steamharness workspace upload hello
pnpm exec steamharness workspace publish hello --release-log "初始发布"
pnpm exec steamharness workspace run hello --target latest --message "hello"

开发环境可以使用本地 server 地址；部署环境建议显式使用正式域名或你的生产端口。

配置来源

配置	说明
STEAMHARNESS_SERVER_URL	workspace CLI 默认 server 地址。
STEAMHARNESS_SERVER_ADMIN_KEY	workspace CLI 的显式管理员覆盖凭证；自动化或恢复场景可直接作为 Bearer 使用。
STEAMHARNESS_REPO_ROOT	workspace CLI 的项目根目录。未设置时从当前目录向上推导。
STEAMHARNESS_CLI_AUTH_DIR	workspace CLI 保存独立登录态 workflow-auth.json 的目录。
STEAMHARNESS_KV_STORE_DIR	steamharness 本地运行时 KV store 目录。
STEAMHARNESS_PERSISTENT_VALUE_STORE_DIR	steamharness 本地运行时 PersistentValue store 目录，也是本地知识库目录。
STEAMHARNESS_FILE_STORE_DIR	steamharness 本地运行时文件 store 目录。

steamharness run/json 要求项目显式声明 steamHarness.projectInfo.dataStorage.mode。STEAMHARNESS_KV_STORE_DIR 只控制 context.storage.local.kv，STEAMHARNESS_PERSISTENT_VALUE_STORE_DIR 只控制 context.storage.local.persistentValue 和本地知识库；二者按项目 UUID 隔离且互不回退。context.storage.server 使用顶层项目 UUID，并从 STEAMHARNESS_SERVER_URL / STEAMHARNESS_SERVER_ADMIN_KEY 或 workspace CLI 保存的 workflow-auth.json 取得登录连接。local 可离线运行，server 必须登录并绑定同 UUID，both 由源码显式选择位置；两端数据不会自动同步。关联项目目录必须用可重复的 --related-project alias=/绝对项目目录 显式传入，CLI 不会扫描父目录或兄弟目录；本地运行时该关系还包含目标项目的知识库与入口调用（按目标项目的授权），服务器位置仅用于数据访问，关联入口仍在本地执行。context.files.createFile(...) 仍使用服务器连接写入 server 文件 API；输入附件解析仍由 STEAMHARNESS_FILE_STORE_DIR 控制。

项目业务值来自项目配置，不加载项目 env，也不回退读取进程变量。宿主部署和通信配置由宿主单独管理。

输出约定

命令族	输出
steamharness run	成功时输出 output node 的内容；失败时输出 JSON 报告到 stderr。
steamharness json	始终输出完整 JSON 执行报告。
steamharness structure	输出 workflow 结构 JSON。
steamharness mcp	stdout 专用于 stdio JSON-RPC；项目日志和诊断写入 stderr。
workspace CLI	输出 server API response JSON，形如 { errCode, errMessage, data }。

后续阅读

• 本地运行和结构检查见 steamharness CLI。
• 将本地 Workflow 连接到 AI 客户端见 steamharness mcp。
• server 上传、发布和下载见 Server Workspace CLI。