Homeboy
Agent-first CLI for deploying, versioning, auditing, and refactoring projects across a fleet.
Changelog
All notable changes to Homeboy CLI are documented in this file. (This file is embedded into the CLI binary and...
Homeboy CLI documentation
This directory contains the markdown docs embedded into the homeboy binary and displayed via homeboy docs. Homeboy is a config-driven...
Config Structures
Configuration ScopedExtensionConfig version — Version constraint string (e.g., ">=2.0.0", "^1.0"). settings — Settings passed to the extension at runtime. GitDeployConfig...
CLI Commands
Commands homeboy — Command Arguments ApiArgs project_id — Project ID command AuditArgs component_id — Component ID or direct filesystem path...
Template Variables
Homeboy supports template variables in several contexts. Both single-brace ({var}) and double-brace ({{var}}) syntaxes are supported everywhere for backward compatibility....
Cross-Compilation Guide
Homeboy can orchestrate releases for any platform, but building native binaries requires access to that platform's toolchain. What Works Anywhere...
`homeboy release`
Synopsis homeboy release <COMPONENT> <BUMP_TYPE> [OPTIONS] Where <BUMP_TYPE> is patch, minor, or major. Also available as: homeboy version bump <COMPONENT>...
`homeboy audit`
Synopsis homeboy audit <component-id|path> [options] Description Audit a component's codebase for convention drift, structural complexity, dead code, duplication, and test...
`homeboy docs`
Synopsis homeboy docs [TOPIC] homeboy docs list homeboy docs audit <component-id> [--features] [--docs-dir <DIR>] homeboy docs map <component-id> [--write] [--include-private]...
`homeboy refactor`
Synopsis homeboy refactor <COMMAND> Description Structural refactoring tools for renaming concepts across a codebase. Walks source files, finds all references...
Commands index
api audit — code convention drift and structural analysis auth build changelog changes cleanup — config health checks and hygiene...
`homeboy cleanup`
Synopsis homeboy cleanup [component-id] [options] Description Identify config drift, stale state, and hygiene issues in component configurations. Checks for broken...
Documentation Generation
Instructions for creating comprehensive user-facing documentation from scratch by analyzing the codebase. Purpose Generate structured documentation in the /docs directory...
Documentation Structure
Standard patterns for organizing documentation files and directories. Directory Conventions /docs Directory User-facing documentation lives in /docs at the project...
Documentation Alignment
Instructions for keeping existing .md documentation synchronized with current codebase implementation. Scope Alignment covers documentation that describes current implementation only....
Documentation Management
Homeboy provides AI agents with consistent instructions for documentation generation and maintenance. These docs serve as the single source of...
Extension Manifest Schema
Extension manifests define extension metadata, runtime behavior, platform behaviors, and integration points. Stored as <extension_id>/<extension_id>.json in the extension directory. Schema...
Project Schema
Project configuration defines deployable environments stored in projects/<id>.json. Schema { "id": "string", "name": "string", "domain": "string", "server_id": "string", "base_path": "string",...
Component Schema
Component configuration defines buildable and deployable units stored in components/<id>.json. Schema { "id": "string", "name": "string", "local_path": "string", "remote_path": "string",...
Portable Component Config (`homeboy.json`)
A homeboy.json file in a repo root defines portable component configuration that travels with the code. Clone a repo, run...
Server Schema
Server configuration defines SSH server connections stored in servers/<id>.json. Schema { "id": "string", "name": "string", "host": "string", "port": number, "user":...
Fleet Schema
Fleet configuration defines named groups of projects stored in fleets/<id>.json. Schema { "id": "string", "project_ids": ["string"], "description": "string" } Fields...
Architecture Overview
Homeboy is a development and deployment automation tool built in Rust with a config-driven architecture. Design Principles Single Source of...
Config Directory Structure
Important: Homeboy uses centralized configuration only. There is no repo-local config file (no .homeboy.toml or .homeboy directory). All configuration lives...
Error Handling Patterns
Homeboy uses a centralized error system for consistent error reporting across all commands. Error Categories Errors are categorized by type...
Release Pipeline System
The release pipeline provides configurable, local orchestration for managing component releases without CI/CD systems. Overview Homeboy's release pipeline is a...
JSON output contract
Homeboy prints JSON to stdout for most commands. Exceptions: homeboy docs prints raw markdown (or newline-delimited topic names for homeboy...
API Client System
The API client provides HTTP request capabilities with template-based authentication per project. Overview Homeboy projects can configure an API client...
Embedded docs: topic resolution and keys
Homeboy embeds markdown files from homeboy/docs/ into the CLI binary at build time. In addition, homeboy docs reads documentation provided...
Execution Context
Execution context provides runtime information to extensions during execution via environment variables and template variable resolution. Overview When Homeboy executes...
Hooks System
Homeboy provides a general-purpose hook/event system for lifecycle extensibility. Both components and extensions can declare hooks that run shell commands...
`homeboy` root command
Synopsis homeboy [OPTIONS] <COMMAND> Description homeboy is a CLI tool for development and deployment automation. Global flags These are provided...