@gethmy/cli

中文文档
0.1.32发布于 2026/11/16ES Module近 30 天下载 2264

One front door for Harmony — hmy installs and dispatches the setup and the agent daemon, so a repository needs one command and one update.

原始使用文档
文档目录6 节
  1. Install
  2. Commands
  3. It re-implements nothing
  4. npx is the fallback, not the steady path
  5. hmy is killed on macOS ( Code Signature Invalid )
  6. An existing per-package install keeps working

@gethmy/cli

hmy — one front door for Harmony.

Harmony ships two binaries from two packages: the MCP server that configures your client and the agent daemon that runs cards. Until this package existed you had to know which package owned the command you wanted, and install both by hand. Now there is one install, one update, and one name in every doc.

Install

npm i -g @gethmy/cli
hmy connect

That is the whole setup. hmy connect configures this repository and your client; hmy agent starts the daemon. hmy setup still reaches connect as a deprecated alias, so a pasted command or a CI job keeps working.

On a machine you may not install to, every command has an npx form — npx @gethmy/mcp connect, npx @gethmy/agent run — and both spellings stay supported. Read "Why not npx" below for what the install buys you.

Commands

Connect
  hmy connect [...]            Configure this repository and your client
  hmy skills status|sync       List the installed Harmony skills, or bring them up to date

Person (a signed-in human, never an API key)
  hmy login [--email <address>]  Sign in with an emailed code; the session stays in the OS keychain
                                 (fallback: ~/.config/hmy/session.json, mode 600)
  hmy whoami | hmy logout
  hmy plan approve P<N> [--revoke] [--project <id>]
                               Approve the plan's current content as yourself
  hmy plan status P<N>         specGate.ready, reasons, approval and the latest grounding

Update
  hmy update [--check]         Install the latest release and run the pending config migrations

Agent
  hmy run                      Start the agent daemon
  hmy status | health | doctor | sweep | resume | gc | recover
  hmy merge --card N [--worktree PATH]
  hmy runs list|show|grep | hmy stats | hmy scan-commands [--write]

Pass-through
  hmy agent <args...>          -> harmony-agent
  hmy harness <args...>        -> harmony-harness
  hmy mcp <args...>            -> harmony-mcp

  hmy --version                Every version AND the file that answered
  hmy help

The three pass-through namespaces are not a convenience — they are what keeps this front door from going stale. A subcommand added to @gethmy/agent tomorrow is reachable as hmy agent <that command> without a new hmy.

It re-implements nothing

Each subcommand resolves the owning package's real bin and hands the process over. hmy merge and harmony-agent merge are the same code with the same gates, so there is no second merge policy for anyone to forget to update. Signals are forwarded, so ctrl-c on hmy run reaches the daemon rather than orphaning it, and the child's exit code is yours.

npx is the fallback, not the steady path

npx -y @gethmy/agent@latest is right for a one-off and wrong as a steady path: @latest does not re-resolve. The npx cache serves the build it first installed, so a machine can keep running a months-old daemon and say nothing about it — measured 2026-09-09, when a restart six minutes after @gethmy/agent 1.38.0 published still ran 1.37.0 out of ~/.npm/_npx/<hash>.

For a command that decides whether a pull request merges, that is the wrong trade. Install once, update in one place:

npm i -g @gethmy/cli@latest

hmy --version prints the resolved path beside every version, which is what tells a frozen cache from an install:

@gethmy/cli 0.1.0
  /usr/local/lib/node_modules/@gethmy/cli/dist/cli.js
@gethmy/agent 1.41.1
  /usr/local/lib/node_modules/@gethmy/cli/node_modules/@gethmy/agent/dist/cli.js
...

hmy is killed on macOS (Code Signature Invalid)

Binaries from cli-v0.1.26 and earlier carry an invalid code signature, and macOS 27.2 ends them with SIGKILL. A reinstall or hmy update to one of those releases downloads the same file. Sign it once by hand:

codesign --force --sign - ~/.hmy/bin/hmy

Releases built after this fix are signed in the release workflow.

An existing per-package install keeps working

If @gethmy/agent or @gethmy/harness is already installed globally, it keeps working beside this package; you do not need to remove it. This package does not ship harmony-agent, harmony-harness or harmony-mcp bins of its own: npm would then have two packages claiming one command name, and which build answered would depend on install order — the silent-staleness problem this package exists to end.

版本与发布记录

@gethmy/cli 共发布 33 个版本,首次发布于 2026/09/18;过去 12 个月发布了 33 个版本。

版本发布日期距今
0.1.32latest2026/11/16今天
0.1.312026/11/114 天前
0.1.302026/11/106 天前
0.1.292026/11/0610 天前
0.1.282026/11/0510 天前
0.1.272026/11/0313 天前

关于 @gethmy/cli 的常见问题

@gethmy/cli 是什么?

One front door for Harmony — hmy installs and dispatches the setup and the agent daemon, so a repository needs one command and one update.

如何安装 @gethmy/cli?

在项目目录运行 npm install @gethmy/cli,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 hmy,可以用 npx hmy 直接运行。

@gethmy/cli 支持 TypeScript 吗?

该包的 package.json 没有声明类型入口。需要类型提示时,可以在 npm 上查找社区维护的 @types/gethmy__cli 是否存在。

@gethmy/cli 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@gethmy/cli 可以商用吗?

@gethmy/cli 使用 未声明 许可。package.json 没有声明许可证。没有许可证的代码默认保留全部权利,商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括,不构成法律意见,请以许可原文为准。

@gethmy/cli 的下载量有多少?

根据 npm 官方下载统计,@gethmy/cli 在 2026/10/17 – 2026/11/15 这 30 天内被下载 2,264 次,日均约 75 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gethmy/cli 还在维护吗?

最新版本 0.1.32 发布于 2026/11/16(今天);至今共发布 33 个版本,其中过去 12 个月发布了 33 个;首次发布于 2026/09/18。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。