Homeboy CLI

Homeboy is a development and deployment automation CLI designed for agentic coding sessions and rapid iteration across multiple projects.

It standardizes configuration-driven workflows for projects, servers, and components while providing extensible automation through modules. Most commands return stable JSON output for machine parsing alongside human-readable output.

Note: This is still early in development. Breaking changes may occur between releases.

Capabilities

Homeboy provides these core capabilities:

Configuration & Context: Manage projects, components, servers, and modules with homeboy init for environment discovery
Deployment: Version-aware deployment with pre-flight checks, dry-run mode, and version comparison
Release Pipelines: Local orchestration replacing CI/CD with configurable steps and module-backed actions
SSH & Remote Operations: Managed SSH connections, remote file operations, log management, and database access
Git Integration: Status, commit (with granular file control), push/pull, and automatic tagging
Database Operations: Table management, querying, search, and SSH tunneling
API Operations: HTTP requests with keychain authentication per project
Version & Changelog: Semantic versioning, changelog management, and changelog finalization
Documentation: Embedded docs, codebase analysis, and bulk documentation generation
Module System: Extensible runtime tools, platform behaviors, and custom release steps

Agent usage (recommended)

Use the Agent Hooks module to guide your coding agent to use Homeboy effectively. Our module provides hooks for Claude Code and OpenCode.

`homeboy init`

homeboy init is a setup helper intended to reduce first-run friction. Depending on your environment it can guide you through (or scaffold) common configuration so you can start using commands like project, server, ssh, and modules sooner.

See: homeboy docs commands/init.

Installation

See the monorepo-level documentation for installation options:

Usage

See CLI documentation for the authoritative command list, embedded docs topics (homeboy docs ...), and JSON contracts.

Initial Setup Workflow

Start with homeboy init to understand your environment and get context. Based on the output:

Create server: homeboy server create <id> --host <host> --user <user>
Create project: homeboy project create <id> <domain> --server <server-id>
Create component: homeboy component create <name> --local-path <path> --remote-path <path> --build-artifact <path>
Link components: homeboy project components add <project> <component>
Verify: homeboy init

Getting Started

# Initialize and explore
homeboy init                            # Get context and next steps
homeboy docs list                       # List all available topics
homeboy docs commands/commands-index     # Browse all commands

# Discovery commands
homeboy project list
homeboy component list
homeboy server list
homeboy module list
homeboy status                         # Show current working context (alias for init)

Component and Project Setup Workflow

# Create a component (buildable/deployable unit)
homeboy component create <name> --local-path . --remote-path <path> --build-artifact <path>
homeboy component set <id> --build-command "./build.sh"
homeboy component set <id> --changelog-target "CHANGELOG.md"

# Create a project (deployable environment)
homeboy project create <name> <domain> --server <server_id>
homeboy project create <name> <domain> --base-path <local-path>  # Local project

# Link components to a project
homeboy project components add <project> <component>
homeboy project components set <project> <component-1> <component-2>

Deployment Workflow

# Check component status without deploying
homeboy deploy <project> --check
homeboy deploy <project> --check --outdated

# Preview what would be deployed
homeboy deploy <project> --all --dry-run

# Deploy components
homeboy deploy <project> component-a component-b
homeboy deploy <project> --all
homeboy deploy <project> --outdated

Release Workflow

# Review changes since last release
homeboy changes <component_id>

# Add changelog entries
homeboy changelog add <component_id> "Added: new feature"
homeboy changelog add <component_id> -m "Fixed: bug" -t fixed

# Plan and run release pipeline
homeboy release plan <component_id>
homeboy release run <component_id>

Module Workflow

# List and install modules
homeboy module list
homeboy module install <git-url>
homeboy module update <module-id>
homeboy module uninstall <module-id>

# Run modules with context
homeboy module run <module-id> --project <project-id>
homeboy module run <module-id> --project <project-id> --component <component-id>
homeboy module run <module-id> --input key=value

# Execute module actions
homeboy module action <module-id> <action-id> --project <project-id>

# Configure module settings
homeboy project set <project-id> --json '{"modules": {"<module-id>": {"settings": {"key": "value"}}}}'
homeboy component set <id> --json '{"modules": {"<module-id>": {"settings": {"key": "value"}}}}'

Git Workflow

# Git operations
homeboy git status <component_id>
homeboy git commit <component_id> -m "Update docs" --files README.md
homeboy git commit <component_id> -m "Release prep" --staged-only
homeboy git push <component_id> --tags
homeboy git pull <component_id>

# Bulk operations
homeboy git status --json '{"component_ids": ["id1", "id2"]}'
homeboy git commit --json '{"components": [{"id": "id1", "message": "msg"}]}'

# Version management
homeboy version show <component_id>
homeboy version bump <component_id> patch
homeboy version set <component_id> 1.2.3

Remote Operations Workflow

# SSH access
homeboy ssh <project_id>               # Interactive shell
homeboy ssh <project_id> "ls -la"      # Execute command
homeboy ssh list                        # List available servers

# File operations
homeboy file list <project_id> <path>
homeboy file read <project_id> <path>
homeboy file write <project_id> <path> < stdin
homeboy file find <project_id> <path> --name "*.php" --type f --max-depth 3
homeboy file grep <project_id> <path> "TODO" --name "*.php" -i

# Log operations
homeboy logs list <project_id>
homeboy logs show <project_id> <path> --lines 100
homeboy logs show <project_id> <path> --follow
homeboy logs search <project_id> <path> "error" -i -C 3

# Database operations
homeboy db tables <project_id>
homeboy db describe <project_id> <table>
homeboy db query <project_id> "SELECT * FROM wp_posts LIMIT 10"
homeboy db search <project_id> <table> --column user_email --pattern "gmail" --exact
homeboy db delete-row <project_id> <table> <row_id>
homeboy db drop-table <project_id> <table>
homeboy db tunnel <project_id>

Platform-Specific Tools (via modules)

# WordPress (via wordpress module)
homeboy wp <project_id> plugin list
homeboy wp <project_id> db export

# Node.js (via nodejs module)
homeboy pm2 <project_id> status
homeboy pm2 <project_id> restart

# Cargo (via rust module)
homeboy cargo <component_id> test

Docs

CLI docs index - Command reference, embedded docs topics, and JSON contracts
Commands index - Complete list of built-in commands
JSON output contract - Stable JSON envelope format
homeboy-modules repository - Public modules and module creation guide

Configuration

Configuration and state live under universal directory ~/.config/homeboy/ (all platforms):

All platforms: ~/.config/homeboy/ (Windows: %APPDATA%\homeboy\)
projects/<id>.json, servers/<id>.json, components/<id>.json - Persistent configuration
modules/<module_id>/<module_id>.json - Module manifests
keys/ - SSH keys
homeboy/homeboy.json - Global defaults

Homeboy does not use repo-local config files. All configuration is managed in the OS config directory.

Module System

Homeboy modules extend functionality with platform-specific tools and behaviors. Modules can provide CLI tools, define platform behaviors, implement release steps, and include their own documentation.

Extensibility Model

The module system enables deep extensibility without modifying the core CLI:

Runtime Tools: Integrate any CLI tool (WP-CLI, PM2, Cargo, GitHub CLI, etc.) as a first-class command
Platform Behaviors: Define database schemas, deployment patterns, and version detection rules
Release Steps: Implement custom pipeline steps that integrate with the core release workflow
Documentation: Modules provide their own embedded documentation that integrates with homeboy docs
Commands: Modules can register top-level CLI commands alongside built-in commands

Modules are JSON manifests that define configuration and runtime behavior. See the homeboy-modules repository for available modules, examples, and implementation details.

Public Module Repository

The official homeboy-modules repository contains publicly available modules:

wordpress: WP-CLI integration with database discovery
nodejs: PM2 process management
rust: Cargo CLI integration
github: GitHub CLI for issues, PRs, and repos
homebrew: Homebrew tap publishing

Install modules from this repository or create your own to extend Homeboy for your specific workflows.

Creating Modules

To create a custom module:

Create a directory structure with a JSON manifest
Define runtime behavior, platform behaviors, and/or release actions
Install locally via symlink for development: homeboy module install <local-path>
Publish to a git repository for sharing

See the homeboy-modules README for detailed module creation guidelines.

Installing Modules

# From git repository
homeboy module install <git-url>

# From local path (creates symlink for development)
homeboy module install <local-path>

# Update a git-cloned module
homeboy module update <module-id>

# Uninstall a module
homeboy module uninstall <module-id>

Module Manifest

Each module includes a JSON manifest (<module_id>/<module_id>.json) defining:

Runtime: run_command, setup_command, ready_check, entrypoint, env
Platform: Database CLI templates, version patterns, deployment behaviors
Release Actions: Custom pipeline steps (e.g., release.publish)
Commands: Additional top-level CLI commands provided by the module
Docs: Embedded documentation topics

Example runtime configuration:

{
  "runtime": {
    "run_command": "./venv/bin/python3 {{entrypoint}} {{args}}",
    "setup_command": "python3 -m venv venv && ./venv/bin/pip install -r requirements.txt",
    "ready_check": "test -f ./venv/bin/python3",
    "entrypoint": "main.py",
    "env": {
      "MY_VAR": "{{modulePath}}/data"
    }
  }
}

Module Settings

Module settings are merged across scopes (later scopes override earlier ones):

Project (projects/<project_id>.json): modules.<module_id>.settings
Component (components/<component_id>.json): modules.<module_id>.settings

Effective settings are passed to modules via environment variables:

HOMEBOY_SETTINGS_JSON: Merged effective settings (JSON)
HOMEBOY_PROJECT_ID: Project ID (when project context is used)
HOMEBOY_COMPONENT_ID: Component ID (when component context is resolved)
HOMEBOY_COMPONENT_PATH: Absolute path to component directory

Configure module settings:

# At project level
homeboy project set <project-id> --json '{"modules": {"<module-id>": {"settings": {"key": "value"}}}}'

# At component level
homeboy component set <component-id> --json '{"modules": {"<module-id>": {"settings": {"key": "value"}}}}'

Module Runtime

Modules can define their own top-level CLI commands and documentation topics. Discover what's available:

homeboy docs list                    # List all topics (core + modules)
homeboy docs <module-topic>          # Render module-provided docs

Executable modules define runtime behavior:

run_command: Shell command to execute the module (supports template variables)
setup_command: Optional command run during install/update
ready_check: Optional command to verify module readiness
env: Optional environment variables to set

Template variables available in run_command:

{{modulePath}}: Module directory path
{{entrypoint}}: Module entrypoint file
{{args}}: Command-line arguments passed to module
Project context variables (when available)

Module Actions

Modules can define actions for execution via homeboy module action:

homeboy module action <module-id> <action-id> --project <project-id> --data '<json>'

Actions can be:

CLI type: Execute module runtime commands
API type: Make HTTP requests to project APIs

Actions are also used in release pipelines as custom steps:

{
  "id": "publish",
  "type": "module.run",
  "config": {
    "module": "github",
    "inputs": [
      {"id": "create_release", "value": "true"}
    ]
  }
}

License

MIT License Created by Chris Huber https://chubes.net

Name		Name	Last commit message	Last commit date
Latest commit History 468 Commits
.github		.github
docs		docs
src		src
tests		tests
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
build.rs		build.rs
dist-workspace.toml		dist-workspace.toml
storage-system-decoupling-plan.md		storage-system-decoupling-plan.md

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Homeboy CLI

Capabilities

Agent usage (recommended)

`homeboy init`

Installation

Usage

Initial Setup Workflow

Getting Started

Component and Project Setup Workflow

Deployment Workflow

Release Workflow

Module Workflow

Git Workflow

Remote Operations Workflow

Platform-Specific Tools (via modules)

Docs

Configuration

Module System

Extensibility Model

Public Module Repository

Creating Modules

Installing Modules

Module Manifest

Module Settings

Module Runtime

Module Actions

License

About

Uh oh!

Releases 152

Packages

Contributors 3

Uh oh!

Languages

License

Extra-Chill/homeboy

Folders and files

Latest commit

History

Repository files navigation

Homeboy CLI

Capabilities

Agent usage (recommended)

homeboy init

Installation

Usage

Initial Setup Workflow

Getting Started

Component and Project Setup Workflow

Deployment Workflow

Release Workflow

Module Workflow

Git Workflow

Remote Operations Workflow

Platform-Specific Tools (via modules)

Docs

Configuration

Module System

Extensibility Model

Public Module Repository

Creating Modules

Installing Modules

Module Manifest

Module Settings

Module Runtime

Module Actions

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 152

Packages 0

Contributors 3

Uh oh!

Languages

`homeboy init`

Packages