@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.