Homeboy CLI

Homeboy is a config-driven automation CLI designed to be used during agentic coding sessions.

It standardizes the “plumbing” work that slows iteration down—project/component discovery, reusable module tools, SSH passthrough, deployments, database operations—while keeping output machine-oriented (most commands return a stable JSON envelope).

Homeboy is intended to make it easier to iterate quickly across many projects at once, with deep automation capabilities provided by modules and CLI tools.

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

Getting started (recommended: use the Homeboy agent skill)

Homeboy works best when your coding agent is explicitly instructed to use it.

• Add the Homeboy skill file at agent-instructions/skills/homeboy/SKILL.md to your agent’s skill set (whatever your agent framework calls this: “skills”, “tools”, or “system prompt attachments”).
• In your agent instructions, tell the agent: “Use Homeboy for deploy, server/ssh, db, and project/component tasks.”

If you are using this repo with an agent, this is the “best path” because it keeps your agent’s actions consistent, safe, and fast.

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
• Homebrew tap

Usage

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

A few common entrypoints:

homeboy docs
homeboy docs --list
homeboy docs commands/project

homeboy list
homeboy project list
homeboy component list
homeboy module list

homeboy pm2 <projectId> status
homeboy wp <projectId> plugin list

homeboy changes <componentId>

homeboy ssh <projectId>                 # interactive passthrough
homeboy logs show <projectId> <path> --follow   # interactive passthrough

Docs

• Docs index
• Commands index
• JSON output contract

Configuration

Configuration and state live under the OS config directory (from dirs::config_dir()), under a homeboy/ folder.

Common defaults:

• macOS: ~/Library/Application Support/homeboy/
• Linux: $XDG_CONFIG_HOME/homeboy/ (fallback: ~/.config/homeboy/)
• Windows: %APPDATA%\\homeboy\\

Common paths:

• projects/<id>.json, servers/<id>.json, and components/<id>.json under the Homeboy config root
• modules/<moduleId>/<moduleId>.json (module manifest; used by the module system)

Notes:

• Homeboy does not use a global project config file like ./homeboy.json.
• Persistent configuration is stored as JSON records under projects/, servers/, and components/.
• Homeboy stores persistent SSH keys under keys/.

See CLI documentation for details.

Agent instructions

Homeboy includes agent-oriented instruction files under agent-instructions/.

• agent-instructions/skills/: skills that can be added to coding agents
• agent-instructions/commands/: reusable command recipes (slash-command style)

These files are not used by Homeboy at runtime; they are meant for humans and coding agents.

SSH

Homeboy connects over SSH using server configuration stored under servers/ inside the OS config directory.

Key management commands (generate/import/use/unset/show) are documented in server.

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.