# 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)

Add this to your agent instructions (AGENTS.md, CLAUDE.md, .cursorrules, etc.):

- Use Homeboy for deployments, server/db ops, version/build management, and documentation.
- Run `homeboy init` first to understand context, then `homeboy docs <topic>` for commands.
- For documentation tasks, see `homeboy docs documentation/index`.

This keeps agent actions consistent and prevents assumptions about project structure.

## `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:

- [Root README](../README.md)
- [Homebrew tap](../homebrew-tap/README.md)

## Usage

See [CLI documentation](docs/index.md) 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:

1. **Create server**: `homeboy server create <id> --host <host> --user <user>`
2. **Create project**: `homeboy project create <id> <domain> --server <server-id>`
3. **Create component**: `homeboy component create <name> --local-path <path> --remote-path <path> --build-artifact <path>`
4. **Link components**: `homeboy project components add <project> <component>`
5. **Verify**: `homeboy init`

### Getting Started

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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)

```bash
# 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

# GitHub (via github module)
homeboy gh <project_id> issue list

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

## Docs

- [CLI docs index](docs/index.md) - Command reference, embedded docs topics, and JSON contracts
- [Commands index](docs/commands/commands-index.md) - Complete list of built-in commands
- [JSON output contract](docs/json-output/json-output-contract.md) - Stable JSON envelope format
- [homeboy-modules repository](../homeboy-modules/) - 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](../homeboy-modules/) for available modules, examples, and implementation details.

### Public Module Repository

The official [homeboy-modules](../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:

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

See the [homeboy-modules README](../homeboy-modules/README.md) for detailed module creation guidelines.

### Installing Modules

```bash
# 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:

```json
{
  "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):

1. Project (`projects/<project_id>.json`): `modules.<module_id>.settings`
2. 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:

```bash
# 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:

```bash
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`:

```bash
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:

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

## License

See `../LICENSE` for the repository license.

Note: `homeboy` (CLI) is distributed under the same license as the rest of this repository unless explicitly stated otherwise in build/distribution tooling.
