Install#

The CLI is the buildhound package on npm. Run it with npx, no install step:

npx buildhound --help

Commands#

Command	What it does
`setup`	Install the Buildhound skill and MCP server for Claude Code, Cursor and Codex when they are present.
`runner add`	Connect this machine as a single-use runner: register, write ~/.buildhound/agent.json, install and start the agent.
`runner status`	Machines, heartbeats, running jobs and the failover map for an account; --local asks the agent on this machine.
`runner set`	Change a machine's routing and settings: pause, performance mode, only when idle or plugged in, trust.
`runner remove`	Deregister a machine (kept 48 hours) and stop the local agent when it is this machine.
`failover`	Inspect routing per label; turn falling back to GitHub-hosted on or off, or override with --set.
`scan`	Audit workflow files for wasted CI spend, priced from run history when a GitHub login is found.
`estimate`	Monthly cost of one workflow file, with the assumptions listed.
`route`	Runner candidates for every job over the spend threshold, ranked by computed cost, with payback for a connected machine.
`rates`	The rate tables the cost model uses, with source and verified date.
`overview`	This month at a glance: jobs on your machines, their hosted cost, fallbacks, machines and what needs you.
`jobs`	Jobs your machines ran, newest first, with wait, run time and what GitHub-hosted would have cost.
`job <id>`	One job's story: waiting, where it ran, re-runs and its cost against GitHub-hosted.
`savings`	Month by month, what the jobs on your machines would have cost on GitHub-hosted, with the calculation.

Output for people and for agents#

In a terminal, commands print plain tables and a few quiet progress lines. When stdout is not a terminal, or with --json, every command prints one JSON object on stdout and keeps logs on stderr, never asks a question, and takes --yes for anything that changes state. When GitHub or payment needs a person, the command returns needs_human with one URL and exits 0.

Every error carries a code, a message and what to do next:

{ "error": { "code": "AUTH_REQUIRED", "message": "...", "next": "gh auth login" } }

Exit codes and tokens#

0 success, 1 findings or a failed check with --fail-on, 2 usage error, 3 auth error, 4 network or GitHub error.

Commands that talk to GitHub take --token, else GITHUB_TOKEN, else the token from gh auth token. Fetched run history is cached for an hour under ~/.cache/buildhound/history.