Skip to content
harnesspmv0.5.1
Color scheme
Contrast
Color scheme
Contrast

CLI reference

In short

  • Projects use init, sync, status, doctor, why, approve and run. Jobs without an install use fetch.
  • Authors use check and new. People use add, remove and update for harnesses on top of the repository’s.
  • Use npx harnesspm … in a project that depends on harnesspm, and npx -y @tenphi/harnesspm … anywhere else.

The npm package is @tenphi/harnesspm. The command it installs is harnesspm. npx harnesspm help lists every command, and npx harnesspm <command> --help shows one, with its options. The specification’s CLI chapter, on GitHub, says exactly what each one does.

Projects

Command What it does
harnesspm init Creates harnesspm.json, adds harnesspm sync to postinstall in a private package or to prepare otherwise, makes CLAUDE.md import AGENTS.md, then runs sync. The script skips the sync when harnesspm is not installed, as in npm ci --omit=dev. Run again, init updates a script from an older version. Stops and changes nothing when @tenphi/harnesspm is not a dependency of the project. Ends with the files to commit.
harnesspm sync Resolves the layers and writes every output. Every full install runs it. In a repository without harnesspm.json, or without installed dependencies, it writes only the per-machine outputs of added harnesses. With CI=true, it writes only per-machine outputs and leaves the committed files to sync --check.
harnesspm sync --check Writes nothing and ignores added harnesses. Fails when the block or the lock is out of date, or when a "pin" package has an unapproved version. For CI.
harnesspm sync --write Writes the committed files with CI=true too, for a job that commits them.
harnesspm status Layers, packages, versions, pending trust, entries an agent could not grant, changes from added harnesses, always-on size per agent, harnesspm blocks that Codex does not reach, and whether telemetry is on.
harnesspm doctor Checks that per-machine files stay out of git and that the outputs are in place. Changes nothing. Each problem names its fix.
harnesspm why <ID> A unit’s owner, source, repository and whether it is editable. For a script, also its command and trust.
harnesspm approve [<package>] Writes the entries that a model run left pending, and approves a "pin" package’s new version. A person runs it.
harnesspm run [--agent <agent>] <plugin>:<script> [-- args] Runs a script of a trusted package, at the version in the lock.
harnesspm fetch Downloads only the harness packages in the lock and checks their integrity. For jobs that do not install dependencies.

Package managers run postinstall and prepare on a full install, but not on npm install <pkg>, npm uninstall or pnpm add. Run npx harnesspm sync after those.

Authors

Command What it does
harnesspm check [<folder>] Validates a harness and warns about files that look like secrets. Run it at prepack.
harnesspm new <kind> <name> Writes a unit from a template. <kind> is rule, skill, agent, script, hook or mcp. Creates harness/plugin.json when the project has none.
harnesspm new patch <rule ID> Writes a patch with a copy of the rule’s sections and registers it: in harness/plugin.json when the rule reaches the project through its own harness’s extends, otherwise in harnesspm.json.

Both new forms take --to <plugin> to write into an added harness, and --to <plugin> --entry to write into its entry for this repository.

People

Command What it does
harnesspm add <source> [--local] [--no-hook] Adds a harness on top of the repository’s: with user scope, or for this repository with --local. Installs a SessionStart hook unless --no-hook, and prints the added always-on rules.
harnesspm remove <source> [--local] Removes it and its outputs. With the last harness of user scope, the hook goes too.
harnesspm update Fetches new versions of added harnesses. Skips working copies with uncommitted changes or unpushed commits.

A source is github:<owner>/<repo>, git:<url>, npm:<name> or a folder.

For agents and hooks

Command What it does
harnesspm mcp [--agent <agent>] <plugin>:<server> Starts a stdio MCP server. Agents call it.
harnesspm track --agent <agent> The command of harnesspm’s own telemetry hooks.

People do not need these.

Exit codes

Code Meaning
0 Success. Pending trust is not an error.
1 Error: an invalid harness, a failed check.
2 harnesspm run refused a script. When a hook calls it, 2 also blocks the event.