Manage standalone component configurations stored under components/<id>.json.

Synopsis

homeboy component [OPTIONS] <COMMAND>

Subcommands

create

homeboy component create [OPTIONS] --local-path <path> --remote-path <path> --build-artifact <path>
homeboy component create --from-repo <path> [--remote-path <path>]

The component ID is derived from the --local-path (or --from-repo) directory name (lowercased). For example, --local-path /path/to/extrachill-api creates a component with ID extrachill-api.

Options:

• --from-repo <path>: create from a repo containing homeboy.json (portable config). Reads version targets, extensions, changelog, etc. from the file. CLI flags override homeboy.json values.
• --json <spec>: JSON input spec for create/update (supports single or bulk)
• --skip-existing: skip items that already exist (JSON mode only)
• --local-path <path>: absolute path to local source / git checkout directory (required unless --from-repo; ID derived from directory name; ~ is expanded). Must be a git repo — not the production deploy target (see component schema)
• --remote-path <path>: remote path relative to project base_path (required unless in homeboy.json)
• --build-artifact <path>: build artifact path relative to local_path (required; must include a filename)
• --version-target <TARGET>: version target in format file or file::pattern (repeatable)
• --build-command <command>: build command to run in local_path (required for homeboy build)
• --extract-command <command>: command to run after upload (optional; supports {artifact} and {targetDir})

Extract Command Execution Context

The extract_command runs inside the target directory. During deploy, Homeboy:

1. Creates the target directory (remote_path joined to project base_path)
2. Uploads the artifact into that directory
3. cd’s into the target directory
4. Executes your extract_command

Template variables:

• {artifact} – The uploaded artifact filename (not a path, just the filename)
• {targetDir} – The full target directory path

Important: Since the command runs inside the target directory, your extract logic must account for where files end up relative to the current directory. The agent configuring the component must understand the build output structure to write a correct extract_command.

show

homeboy component show <id>

set

homeboy component set <id> --json <JSON>
homeboy component set <id> '<JSON>'
homeboy component set --json <JSON>   # id may be provided in JSON body
homeboy component set <id> --key value   # dynamic flags
homeboy component set <id> --json '{}' -- --key value   # combining --json with dynamic flags

Updates a component by merging a JSON object into components/<id>.json.

Options:

• --json <JSON>: JSON object to merge into config (supports @file and - for stdin)
• --replace <field>: replace array fields instead of union (repeatable)
• --key value: Dynamic flags that map directly to JSON keys (e.g., --changelog-target "CHANGELOG.md")

Important: When combining --json with dynamic flags, you must add an explicit -- separator before the dynamic flags:

# Correct: explicit separator before dynamic flags
homeboy component set my-plugin --json '{"type":"plugin"}' -- --build_command "npm run build"

# Incorrect: will fail with "unexpected argument"
homeboy component set my-plugin --json '{"type":"plugin"}' --build_command "npm run build"

Notes:

• If the JSON contains an id field that differs from <id>, the component is automatically renamed first (equivalent to calling rename), then the remaining fields are merged. Project references are updated automatically.
• Use null in JSON to clear a field (for example, {"post_version_bump_commands": null}).

Release configuration

Components may define a release block for component-scoped release planning. You can set it with:

homeboy component set <id> --json '{"release": {"enabled": true, "steps": []}}'

Components also define extension usage via extensions:

homeboy component set <id> --json '{"extensions": {"github": {"settings": {}}, "rust": {"settings": {}}}}'

{
  "release": {
    "enabled": true,
    "steps": [
      { "id": "build", "type": "build", "label": "Build", "needs": [], "config": {} }
    ],
    "settings": { "distTarget": "homeboy" }
  }
}

Setting changelog_target

To configure changelog tracking for a component:

# Using dynamic flag (recommended)
homeboy component set <id> --changelog-target "CHANGELOG.md"
homeboy component set <id> --changelog-target "docs/CHANGELOG.md"

# Using JSON format
homeboy component set <id> '{"changelog_target": "docs/CHANGELOG.md"}'

Note: changelog_target is a string path relative to local_path, not an object.

delete

homeboy component delete <id>

Deletion is safety-checked:

• If the component is referenced by one or more projects, the command errors and asks you to remove it from those projects first.

rename

homeboy component rename <id> <new-id>

Renames a component by changing its ID and rewriting any project files that reference the old ID.

Notes:

• new-id is lowercased before writing.
• The component is moved from components/<old-id>.json to components/<new-id>.json.
• Project references are updated by rewriting each project config that uses the component.

Example:

homeboy component rename extra-chill-api extrachill-api

list

homeboy component list

projects

homeboy component projects <id>

Lists all projects that reference the given component. Returns both project IDs and full project objects.

shared

homeboy component shared [id]

Shows which components are shared across projects.

Without an ID, returns a map of all components and the projects using them:

homeboy component shared
# → my-plugin: [site-a, site-b, site-c]
# → homeboy: [project-1, project-2]

With an ID, shows only projects using that specific component:

homeboy component shared my-plugin
# → [site-a, site-b, site-c]

This is useful for:

• Understanding component distribution across your projects
• Planning coordinated deployments with deploy --shared
• Identifying candidates for fleet grouping

JSON output

Note: all command output is wrapped in the global JSON envelope described in the JSON output contract. The object below is the data payload.

Note: all command output is wrapped in the global JSON envelope described in the JSON output contract. The object below is the data payload.

{
  "command": "component.create|component.show|component.set|component.delete|component.rename|component.list|component.projects",
  "component_id": "<id>|null",
  "success": true,
  "updated_fields": ["local_path", "remote_path"],
  "component": {},
  "components": [],
  "import": null,
  "project_ids": ["project-1", "project-2"],
  "projects": []
}

Note: all command output is wrapped in the global JSON envelope described in the JSON output contract. The object below is the data payload.

• In JSON import mode (homeboy component create --json ...), command is still component.create and import is populated.
• updated_fields is empty for all actions except set/rename.
• rename does not include the old ID; capture it from your input if needed.
• project_ids and projects are only populated for component.projects.

Related

• build
• deploy
• fleet
• project
• JSON output contract