Commands

• homeboy —

Command Arguments

ApiArgs

• project_id — Project ID
• command

AuditArgs

• component_id — Component ID or direct filesystem path to audit
• conventions — Only show discovered conventions (skip findings)
• fix — Generate fix stubs for outlier files (dry run by default)
• write — Apply fixes to disk (requires –fix)
• baseline — Save current audit state as baseline for future comparisons
• ignore_baseline — Skip baseline comparison even if a baseline exists

AuthArgs

• command

BuildArgs

• json — JSON input spec for bulk operations: {"componentIds": ["id1", "id2"]}
• target_id — Target ID: component ID or project ID (when using –all)
• component_ids — Additional component IDs (enables project/component order detection)
• all — Build all components in the project
• path — Override local_path for this build (use a workspace clone or temp checkout)

ChangelogArgs

• show_self — Show Homeboy’s own changelog (release notes)
• command

ChangesArgs

• target_id — Target ID: component ID (single mode) or project ID (if followed by component IDs)
• component_ids — Component IDs to filter (when target_id is a project)
• project — Show changes for all components in a project (alternative to positional project mode)
• json — JSON input spec for bulk operations: {"componentIds": ["id1", "id2"]}
• since — Compare against specific tag instead of latest
• git_diffs — Include commit range diff in output (uncommitted diff is always included)

CleanupArgs

• component_id — Component to check (omit for all components)
• severity — Show only issues of a specific severity: error, warning, info
• category — Show only issues in a specific category: local_path, remote_path, version_targets, extensions

CliArgs

• tool
• identifier
• args

ComponentArgs

• command

ConfigArgs

• command

DbArgs

• command

DeployArgs

• target_id — Target ID: project ID or component ID (order is auto-detected)
• component_ids — Additional component IDs (enables project/component order detection)
• project — Explicit project ID (takes precedence over positional detection)
• component — Explicit component IDs (takes precedence over positional)
• json — JSON input spec for bulk operations
• all — Deploy all configured components
• outdated — Deploy only outdated components
• dry_run — Preview what would be deployed without executing
• check — Check component status without building or deploying
• force — Deploy even with uncommitted changes
• projects — Deploy to multiple projects (comma-separated or repeated)
• fleet — Deploy to all projects in a fleet
• shared — Deploy to all projects using the specified component(s)
• keep_deps — Keep build dependencies (skip post-deploy cleanup)

DocsArgs

• command
• topic — Topic path (e.g., ‘commands/deploy’) or ‘list’ to show available topics

ExtensionArgs

• command

FileArgs

• command

FleetArgs

• command

GitArgs

• command

InitArgs

• all — Show all components, extensions, projects, and servers
• json — Accept –json for compatibility (output is JSON by default)

LintArgs

• component — Component name to lint
• fix — Auto-fix formatting issues before validating
• summary — Show compact summary instead of full output
• file — Lint only a single file (path relative to component root)
• glob — Lint only files matching glob pattern (e.g., "inc/**/*.php")
• changed_only — Lint only files modified in the working tree (staged, unstaged, untracked)
• errors_only — Show only errors, suppress warnings
• sniffs — Only check specific sniffs (comma-separated codes)
• exclude_sniffs — Exclude sniffs from checking (comma-separated codes)
• category — Filter by category: security, i18n, yoda, whitespace
• setting — Override settings as key=value pairs
• path — Override local_path for this lint run (use a workspace clone or temp checkout)
• json — Accept –json for compatibility (output is JSON by default)

LogsArgs

• command

DynamicSetArgs

• id — Entity ID (optional if provided in JSON body)
• spec — JSON spec (positional, supports @file and – for stdin)
• json — Explicit JSON spec (takes precedence over positional)
• base64 — Base64-encoded JSON spec (bypasses shell escaping issues)
• replace — Replace these fields instead of merging arrays
• extra — Dynamic key=value flags (e.g., –remote_path /var/www). When combined with –json, add ‘–‘ separator first: homeboy component set ID --json '{}' -- --key value

ProjectArgs

• command

RefactorArgs

• command

ReleaseArgs

• component_id — Component ID
• bump_type
• dry_run — Preview what will happen without making changes
• json — Accept –json for compatibility (output is JSON by default)
• deploy — Deploy to all projects using this component after release
• recover — Recover from an interrupted release (tag + push current version)

ServerArgs

• command

KeyArgs

• command

SshArgs

• target — Target ID (project or server; project wins when ambiguous)
• command — Command to execute (omit for interactive shell). Examples: homeboy ssh my-project — ls -la homeboy ssh my-project — wp plugin list If you need shell operators (&&, |, redirects), pass a single quoted string: homeboy ssh my-project "cd /var/www && ls | head"
• as_server — Force interpretation as server ID
• subcommand

StatusArgs

• uncommitted — Show only components with uncommitted changes
• needs_bump — Show only components that need a version bump
• ready — Show only components ready to deploy
• docs_only — Show only components with docs-only changes
• all — Show all components regardless of current directory context

TestArgs

• component — Component name to test
• skip_lint — Skip linting before running tests
• fix — Auto-fix linting issues before running tests
• setting — Override settings as key=value pairs
• path — Override local_path for this test run (use a workspace clone or temp checkout)
• args — Additional arguments to pass to the test runner (after –)
• json — Accept –json for compatibility (output is JSON by default)

TransferArgs

• source — Source: local path or server_id:/path
• destination — Destination: local path or server_id:/path
• recursive — Transfer directories recursively
• compress — Compress data during transfer
• dry_run — Show what would be transferred without doing it
• exclude — Exclude patterns (can be specified multiple times)

UpgradeArgs

• check — Check for updates without installing
• force — Force upgrade even if already at latest version
• no_restart — Skip automatic restart after upgrade
• method — Override install method detection (homebrew|cargo|source|binary)
• json — Accept –json for compatibility (output is JSON by default)

VersionArgs

• command

SshResolveArgs

• id — Bare ID (tries project first, then server)
• project — Force project resolution
• server — Force server resolution

Subcommands

ApiCommand

• Get — Make a GET request
• endpoint — API endpoint (e.g., /wp/v2/posts)
• Post — Make a POST request
• endpoint — API endpoint
• body — JSON body
• Put — Make a PUT request
• endpoint — API endpoint
• body — JSON body
• Patch — Make a PATCH request
• endpoint — API endpoint
• body — JSON body
• Delete — Make a DELETE request
• endpoint — API endpoint

AuthCommand

• Login — Authenticate with a project’s API
• project — Project ID
• identifier — Username or email
• password — Password (or read from stdin)
• Logout — Clear stored authentication for a project
• project — Project ID
• Status — Show authentication status for a project
• project — Project ID

ChangelogCommand

• Show — Show a changelog (Homeboy’s own if no component specified)
• component_id — Component ID to show changelog for
• EXAMPLES — Add changelog items to the configured "next" section Examples: homeboy changelog add my-plugin "Fixed login bug" homeboy changelog add my-plugin "Removed legacy API" –type Removed homeboy changelog add my-plugin -m "Added search" -m "Added filters"
• Add
• json — JSON input spec for batch operations. Use "-" to read from stdin, "@file.json" to read from a file, or an inline JSON string.
• component_id — Component ID (non-JSON mode)
• positional_message — Changelog item content (positional, for backward compatibility)
• messages — Changelog message (repeatable: -m "first" -m "second")
• entry_type — Changelog subsection type (Added, Changed, Deprecated, Removed, Fixed, Security, Refactored)
• Init — Initialize a new changelog file
• path — Path for the changelog file (relative to component)
• configure — Also update component config to add changelogTargets
• component_id — Component ID

ComponentCommand

• Create — Create a new component configuration
• json — JSON input spec for create/update (supports single or bulk)
• skip_existing — Skip items that already exist (JSON mode only)
• local_path — Absolute path to local source directory (ID derived from directory name)
• remote_path — Remote path relative to project basePath
• build_artifact — Build artifact path relative to localPath
• version_targets — Version targets in the form "file" or "file::pattern" (repeatable). For complex patterns, use –version-targets @file.json to avoid shell escaping
• version_targets_json
• build_command — Build command to run in localPath
• extract_command — Extract command to run after upload (e.g., "unzip -o {artifact} && rm {artifact}")
• changelog_target — Path to changelog file relative to localPath
• extensions — Extension(s) this component uses (e.g., "wordpress"). Repeatable.
• Show — Display component configuration
• id — Component ID
• Set — Update component configuration fields Supports dedicated flags for common fields (e.g., –local-path, –build-command) as well as –json for arbitrary updates. When combining –json with dynamic trailing flags, use ‘–‘ separator.
• args
• local_path — Absolute path to local source directory
• remote_path — Remote path relative to project basePath
• build_artifact — Build artifact path relative to localPath
• build_command — Build command to run in localPath
• extract_command — Extract command to run after upload (e.g., "unzip -o {artifact} && rm {artifact}")
• changelog_target — Path to changelog file relative to localPath
• version_targets — Version targets in the form "file" or "file::pattern" (repeatable). Same format as component create --version-target.
• extensions — Extension(s) this component uses (e.g., "wordpress"). Repeatable.
• Delete — Delete a component configuration
• id — Component ID
• Rename — Rename a component (changes ID directly)
• id — Current component ID
• new_id — New component ID (should match repository directory name)
• List — List all available components
• Projects — List projects using this component
• id — Component ID
• Shared — Show which components are shared across projects
• id — Specific component ID to check (optional, shows all if omitted)
• AddVersionTarget — Add a version target to a component
• id — Component ID
• file — Target file path relative to component root
• pattern — Regex pattern with capture group for version

ConfigCommand

• Show — Display configuration (merged defaults + file)
• builtin — Show only built-in defaults (ignore homeboy.json)
• Set — Set a configuration value at a JSON pointer path
• pointer — JSON pointer path (e.g., /defaults/deploy/scp_flags)
• value — Value to set (JSON)
• Remove — Remove a configuration value at a JSON pointer path
• pointer — JSON pointer path (e.g., /defaults/deploy/scp_flags)
• Reset — Reset configuration to built-in defaults (deletes homeboy.json)
• Path — Show the path to homeboy.json

DbCommand

• Tables — List database tables
• project_id — Project ID
• args — Optional subtarget
• Describe — Show table structure
• project_id — Project ID
• args — Optional subtarget and table name
• Query — Execute SELECT query
• project_id — Project ID
• args — Optional subtarget and SQL query
• Search — Search table by column value
• project_id — Project ID
• table — Table name
• column — Column to search
• pattern — Search pattern
• exact — Use exact match instead of LIKE
• limit — Maximum rows to return
• subtarget — Optional subtarget
• DeleteRow — Delete a row from a table
• project_id — Project ID
• args — Table name and row ID
• DropTable — Drop a database table
• project_id — Project ID
• args — Table name
• Tunnel — Open SSH tunnel to database
• project_id — Project ID
• local_port — Local port to bind

DocsCommand

• Scaffold — Analyze codebase and report documentation status (read-only)
• component_id — Component to analyze
• docs_dir — Docs directory to check for existing documentation (default: docs)
• source_dirs — Source directories to analyze (comma-separated, or repeat flag). Overrides auto-detection.
• source_extensions — File extensions to detect as source code (default: php,rs,js,ts,py,go,java,rb,swift,kt)
• detect_by_extension — Include all directories containing source files (extension-based detection)
• Audit — Audit documentation for broken links and stale references
• component_id — Component ID or direct filesystem path to audit
• docs_dir — Docs directory relative to component/project root (overrides config, default: docs)
• features — Include full list of all detected features in output
• Generate — Generate documentation files from JSON spec
• spec — JSON spec (positional, supports @file and – for stdin)
• json — Explicit JSON spec (takes precedence over positional)
• from_audit — Generate docs from audit output (pipe from docs audit --features or use @file)
• dry_run — Show what would be generated without writing files

ExtensionCommand

• List — Show available extensions with compatibility status
• project — Project ID to filter compatible extensions
• Show — Show detailed information about a extension
• extension_id — Extension ID
• Run — Execute a extension
• extension_id — Extension ID
• project — Project ID (defaults to active project)
• component — Component ID (required when ambiguous)
• input — Input values as key=value pairs
• step — Run only specific steps (comma-separated, e.g. –step phpunit,phpcs)
• skip — Skip specific steps (comma-separated, e.g. –skip phpstan,lint)
• args — Arguments to pass to the extension (for CLI extensions)
• stream — Stream output directly to terminal (default: auto-detect based on TTY)
• no_stream — Disable streaming and capture output (default: auto-detect based on TTY)
• Setup — Run the extension’s setup command (if defined)
• extension_id — Extension ID
• Install — Install a extension from a git URL or local path
• source — Git URL or local path to extension directory
• id — Override extension id
• Update — Update an installed extension (git pull)
• extension_id — Extension ID (omit with –all to update everything)
• all — Update all installed extensions
• force — Force update even with uncommitted changes
• Uninstall — Uninstall a extension
• extension_id — Extension ID
• Action — Execute a extension action (API call or builtin)
• extension_id — Extension ID
• action_id — Action ID
• project — Project ID (required for API actions)
• data — JSON array of selected data rows
• Exec — Run a tool from a extension’s vendor directory
• extension_id — Extension ID
• component — Component ID (sets working directory to component path)
• args — Command and arguments to run
• Set — Update extension manifest fields
• extension_id — Extension ID (optional if provided in JSON body)
• json — JSON object to merge into manifest (supports @file and – for stdin)
• replace — Replace these fields instead of merging arrays

FileCommand

• List — List directory contents
• project_id — Project ID
• path — Remote directory path
• Read — Read file content
• project_id — Project ID
• path — Remote file path
• raw — Output raw content only (no JSON wrapper)
• Write — Write content to file (from stdin)
• project_id — Project ID
• path — Remote file path
• Delete — Delete a file or directory
• project_id — Project ID
• path — Remote path to delete
• recursive — Delete directories recursively
• Rename — Rename or move a file
• project_id — Project ID
• old_path — Current path
• new_path — New path
• Find — Find files by name pattern
• project_id — Project ID
• path — Directory path to search
• name — Filename pattern (glob, e.g., "*.php")
• file_type — File type: f (file), d (directory), l (symlink)
• max_depth — Maximum directory depth
• Grep — Search file contents
• project_id — Project ID
• path — Directory path to search
• pattern — Search pattern
• name — Filter files by name pattern (e.g., "*.php")
• max_depth — Maximum directory depth
• ignore_case — Case insensitive search
• Download — Download a file or directory from remote server
• project_id — Project ID
• path — Remote file path
• local_path — Local destination path (defaults to current directory)
• recursive — Download directories recursively
• Edit — Edit file with line-based or pattern-based operations

FleetCommand

• Create — Create a new fleet
• id — Fleet ID
• projects — Project IDs to include (comma-separated or repeated)
• description — Description of the fleet
• Show — Display fleet configuration
• id — Fleet ID
• Set — Update fleet configuration
• args
• Delete — Delete a fleet
• id — Fleet ID
• List — List all fleets
• Add — Add a project to a fleet
• id — Fleet ID
• project — Project ID to add
• Remove — Remove a project from a fleet
• id — Fleet ID
• project — Project ID to remove
• Projects — Show projects in a fleet
• id — Fleet ID
• Components — Show component usage across a fleet
• id — Fleet ID
• Status — Show component versions across a fleet (local only)
• id — Fleet ID
• Check — Check component drift across a fleet (compares local vs remote)
• id — Fleet ID
• outdated — Only show components that need updates
• Sync — [DEPRECATED] Use ‘homeboy deploy’ instead. See issue #101.
• id — Fleet ID
• category — Sync only specific categories (repeatable)
• dry_run — Show what would be synced without doing it
• leader — Override leader server (defaults to fleet-sync.json config)

GitCommand

LogsCommand

• List — List pinned log files
• project_id — Project ID
• Show — Show log file content (shows all pinned logs if path omitted)
• project_id — Project ID
• path — Log file path (optional – shows all pinned logs if omitted)
• lines — Number of lines to show
• follow — Follow log output (like tail -f)
• local — Execute locally instead of via SSH (for when running on the target server)
• Clear — Clear log file contents
• project_id — Project ID
• path — Log file path
• local — Execute locally instead of via SSH
• Search — Search log file for pattern
• project_id — Project ID
• path — Log file path
• pattern — Search pattern
• ignore_case — Case insensitive search
• lines — Limit to last N lines before searching
• context — Lines of context around matches
• local — Execute locally instead of via SSH

ProjectCommand

• List — List all configured projects
• Show — Show project configuration
• project_id — Project ID
• Create — Create a new project
• json — JSON input spec for create/update (supports single or bulk)
• skip_existing — Skip items that already exist (JSON mode only)
• id — Project ID (CLI mode)
• domain — Public site domain (CLI mode)
• server_id — Optional server ID
• base_path — Optional remote base path
• table_prefix — Optional table prefix
• Set — Update project configuration fields
• args
• Remove — Remove items from project configuration arrays
• project_id — Project ID (optional if provided in JSON body)
• spec — JSON spec (positional, supports @file and – for stdin)
• json — Explicit JSON spec (takes precedence over positional)
• Rename — Rename a project (changes ID)
• project_id — Current project ID
• new_id — New project ID
• Components — Manage project components
• command
• Pin — Manage pinned files and logs
• command
• Delete — Delete a project configuration
• project_id — Project ID

ProjectComponentsCommand

• List — List associated components
• project_id — Project ID
• Set — Replace project components with the provided list
• project_id — Project ID
• component_ids — Component IDs
• Add — Add one or more components
• project_id — Project ID
• component_ids — Component IDs
• Remove — Remove one or more components
• project_id — Project ID
• component_ids — Component IDs
• Clear — Remove all components
• project_id — Project ID

ProjectPinCommand

• List — List pinned items
• project_id — Project ID
• Add — Pin a file or log
• project_id — Project ID
• path — Path to pin (relative to basePath or absolute)
• label — Optional display label
• tail — Number of lines to tail (logs only)
• Remove — Unpin a file or log
• project_id — Project ID
• path — Path to unpin

RefactorCommand

• Rename — Rename a term across the codebase with case-variant awareness
• from — Term to rename from
• to — Term to rename to
• component — Component ID (uses its local_path as the root)
• path — Directory path to refactor (alternative to –component)
• scope — Scope: code, config, all (default: all)
• literal — Exact string matching (no boundary detection, no case variants)
• write — Apply changes to disk (default is dry-run)

ServerCommand

• Create — Register a new SSH server
• json — JSON input spec for create/update (supports single or bulk)
• skip_existing — Skip items that already exist (JSON mode only)
• id — Server ID (CLI mode)
• host — SSH host
• user — SSH username
• port — SSH port (default: 22)
• Show — Display server configuration
• server_id — Server ID
• Set — Modify server settings
• args
• Delete — Remove a server configuration
• server_id — Server ID
• List — List all configured servers
• Key — Manage SSH keys

KeyCommand

• Generate — Generate a new SSH key pair and set it for this server
• server_id — Server ID
• Show — Display the public SSH key
• server_id — Server ID
• Import — Import an existing SSH private key and set it for this server
• server_id — Server ID
• private_key_path — Path to private key file
• Use — Use an existing SSH private key file path for this server
• server_id — Server ID
• private_key_path — Path to private key file
• Unset — Unset the server SSH identity file (use normal SSH resolution)
• server_id — Server ID

SshSubcommand

• List — List configured SSH server targets

VersionCommand

• Show — Show current version (default: homeboy binary)
• component_id — Component ID (optional – shows homeboy binary version when omitted)
• path — Override local_path for version file lookup
• Set — [DEPRECATED] Use ‘homeboy version bump’ or ‘homeboy release’ instead. See issue #259.
• component_id — Component ID
• new_version — New version (e.g., 1.2.3)
• path — Override local_path for version file lookup
• Bump — Bump version with semantic versioning (alias for release)
• component_id — Component ID
• bump_type — Version bump type (patch, minor, major)
• dry_run — Preview what will happen without making changes
• path — Override local_path for version operations

Commands

• Project — Manage project configuration
• Ssh — SSH into a project server or configured server
• Server — Manage SSH server configurations
• Test — Run tests for a component
• Lint — Lint a component
• Cleanup — Identify config drift, stale state, and hygiene issues
• Db — Database operations
• File — Remote file operations
• Fleet — Manage fleets (groups of projects)
• Logs — Remote log viewing
• Transfer — Transfer files between servers
• Deploy — Deploy components to remote server
• Component — Manage standalone component configurations
• Config — Manage global Homeboy configuration
• Extension — Execute CLI-compatible extensions
• Init — Get repo context (read-only, creates no state)
• Status — Actionable component status overview
• Docs — Display CLI documentation
• Changelog — Changelog operations
• Git — Git operations for components
• Version — Version management for components
• Build — Build a component
• Changes — Show changes since last version tag
• Release — Plan release workflows
• Audit — Audit code conventions and detect architectural drift
• Refactor — Structural refactoring (rename terms across codebase)
• Auth — Authenticate with a project’s API
• Api — Make API requests to a project
• Upgrade — Upgrade Homeboy to the latest version
• Update — Alias for upgrade
• List — List available commands (alias for –help)