The hm command line

The hm program that ships inside the desktop app, how to run it from a terminal, and how it knows which Works to act on.

The desktop ships with a command-line program called hm inside it, and the two act on the same Works under the same rules. The day-to-day work can be done in the desktop, starting with installing the desktop, and this section is for when you want the same commands in a terminal, a script, or an agent's toolbelt.

Where the program is

On macOS, hm ships inside the application bundle, beside the desktop itself:

/Applications/hm.app/Contents/MacOS/hm

It is the same build as the app around it, so the version the desktop runs and the version you run by hand never drift apart. Check it with:

/Applications/hm.app/Contents/MacOS/hm --version

The bundle does not put hm on your shell's PATH. To type hm on its own, add an alias to your shell profile:

alias hm=/Applications/hm.app/Contents/MacOS/hm

The rest of these pages write hm for short.

When the desktop starts, it looks for hm in a fixed order: an explicit HM_BIN override if one is set, then the copy inside its own bundle, then PATH. Unless you set HM_BIN, the bundled copy wins over any other hm on your machine.

Finding your way around

hm --help lists the command groups, and every group and subcommand takes --help too:

hm --help
hm ticket --help
hm run dispatch --help

For the whole catalogue in one place, with the lifecycle a piece of work follows and which role may run what, use hm workflow show. It reads no Works, so it is safe to run straight after installing. Tickets and manifests from the terminal walks through it.

Choosing the Works a command acts on

Most commands act on one Works, and there are two ways to name it:

pass --works with the path to the Works folder. Every command accepts it;
set HM_WORKS in your environment. --works overrides it when both are set.

hm --works <path-to-your-works> manifest list

A few commands need no Works at all: hm workflow show, hm --version, and hm --help.

What the command line can and cannot do

The terminal gets no extra authority. hm records every change it makes to the Works in the ledger, exactly as it does when the desktop runs it, and it enforces the same checks: a ticket that is not ready is not dispatched, and work that is not complete is not landed. An agent working a ticket changes the Works only by calling hm, which is why the same program can serve a person at a keyboard, the desktop, and an agent over MCP.

The pages that follow cover the parts people most often run by hand:

Checked against docs/plans/e-app-3-embedded-cli.md, reviewed 2026-09-14. That file is what makes these steps true; this page is a reading of it, and is not where it is edited.