CLI Overview

buddy-agent-harness provides six commands. init links the canonical .agents/skills directory into the harnesses that cannot read it directly; doctor reports whether those links still resolve, along with the instruction bridges into AGENTS.md that the init-buddy-agent-harness skill writes, and any drift between a golden MCP server set and each harness’s copy of it; mcp project writes that golden set into each harness’s own MCP file, and mcp reconcile imports a harness-side change back into it; dep-plugins derives a marketplace catalog for plugins shipped by the repository’s own dependencies, so a harness can install them; reference reads on-demand reference documents by name through layered tiers; governance, which reference replaces, is deprecated.

Run bare, buddy-agent-harness answers with the doctor report under a bin: and description: header. doctor is the one you run on its own:

npx -y buddy-agent-harness doctor

init runs behind the init-buddy-agent-harness skill. Installing the package alongside repobuddy mounts both commands on buddy, as buddy agent-harness doctor and buddy agent-harness init.

Skill or CLI?

The CLI is the mechanical half. It creates projections, records the enabled harnesses, and reports conflicts. It does not read your existing CLAUDE.md, move skills, merge instructions, or write the instruction bridges.

Use the init-buddy-agent-harness skill when adopting or migrating a repository. That is the whole job, and the CLI is step 4 of it. Use the CLI directly when the repository is already consolidated and you only need the links refreshed or a new harness enabled.

doctor is the read-only half of the same picture. It writes nothing and always exits 0; each finding names its repair — an init command for a skills bridge, and the init-buddy-agent-harness skill for an instruction bridge, which no command rebuilds. Reach for it when a harness loads no project skills, most often after a clone on Windows, or when one appears to be ignoring AGENTS.md. The doctor-buddy-agent-harness skill wraps the same command for an agent.

Both commands print TOON by default and accept --format text for a report a person can read:

npx -y buddy-agent-harness doctor --format text

Every command carries examples in its --help. A failure is a coded error on stdout, with a help line, never prose on stderr. Full flags, output shape, and conflict behavior: init, doctor, mcp project and mcp reconcile, dep-plugins, reference, and governance.