Synopsis

homeboy [OPTIONS] <COMMAND>

Description

homeboy is headless automation for agentic software engineering workflows. It keeps local developers, CI, scheduled jobs, and coding agents on the same component-aware command surface and structured evidence contract.

Global flags

These are provided by clap:

• --version / -V: print version and exit
• --help / -h: print help and exit
• --output <PATH>: write the structured JSON envelope to a file in addition to stdout
• --placement <auto|local|lab>: select automatic placement, intentional controller execution, or required Lab execution
• --artifact-root <DIR>: copy persisted run artifacts to a specific directory
• --runner <RUNNER_ID>: route commands with portable Lab offload support to a connected Homeboy Lab runner
• --allow-local-fallback: permit a selected Lab runner to fall back to local execution after offload preflight fails
• --allow-dirty-lab-workspace: permit Lab git workspace materialization to overwrite a dirty runner-side checkout

--output is a global flag, so pass it before the subcommand:

homeboy --output /tmp/homeboy-results/review.json review my-component --changed-since=origin/main

Resource policy warnings are stderr-only preflight notices. They currently apply to hot commands such as bench, rig up, fleet exec, full-workspace audit / lint / test runs, and changed-scope audit / lint / test runs when homeboy self doctor sees a warm or hot machine. Non-interactive hot commands fail fast unless the work is routed through Lab/runner-hosted execution or the caller explicitly accepts local pressure. For portable hot commands with a default Lab runner, including controller spec materialization commands, Homeboy auto-selects the default runner when --runner is omitted. Use --placement local only when controller-machine execution is intentional; use --placement lab when local fallback is unacceptable. Removed placement flags are rejected with a migration error; Homeboy provides no legacy support. When --runner <RUNNER_ID> explicitly routes a portable command, resource output reports controller preflight and transport overhead separately from the runner workload; it does not recommend the supplied runner again or describe the workload as starting locally. Any authorized local fallback is reported by the Lab offload transition with its exact reason.

Not every hot command is offloadable. Lab offload only applies to commands with a portable runner contract; local-only hot commands keep running locally and explain why --runner is unavailable.

Subcommands

Run homeboy --help for the exact supported subcommands, or homeboy self docs commands/commands-index for the runtime-derived index.

Automation that needs command safety, docs, output, and Lab metadata should use the first-class recursive manifest surface:

homeboy contract manifest