# `homeboy component`

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

## Synopsis

```sh
homeboy component [OPTIONS] <COMMAND>
```


## Subcommands

### `create`

```sh
homeboy component create [OPTIONS] --local-path <path> --remote-path <path> --build-artifact <path>
```

The component ID comes from an existing `homeboy.json` `id` when present; otherwise it is derived from the `--local-path` directory name (lowercased). For example, `--local-path /path/to/extrachill-api` creates a component with ID `extrachill-api`.

Options:

- `--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; ID derived from directory name; `~` is expanded). Must be a git repo — not the production deploy target (see [component schema](../schemas/component-schema.md#local_path-vs-remote_path))
- `--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)
- `--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`

```sh
homeboy component show <id>
```

### `set`

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

```sh
# Correct: explicit separator before dynamic flags
homeboy component set my-plugin --json '{"type":"plugin"}' -- --docs_dir "docs"

# Incorrect: will fail with "unexpected argument"
homeboy component set my-plugin --json '{"type":"plugin"}' --docs_dir "docs"
```

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.
- `remote_url` and `triage_remote_url` must be GitHub remotes (`https://github.com/<owner>/<repo>.git` or `git@github.com:<owner>/<repo>.git`). Local filesystem paths and unsupported providers are rejected when writing component config.
- 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:

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

Components also define extension usage via `extensions`:

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

`homeboy build`, `homeboy lint`, `homeboy test`, `homeboy bench`, and `homeboy trace` check component-owned `scripts.<capability>` first, then linked extensions. Components do not support a standalone `build_command` field; use `scripts.build` for component-owned shell builds.

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

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

```sh
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`

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

```sh
homeboy component rename extra-chill-api extrachill-api
```

### `list`

```sh
homeboy component list
```

### `projects`

```sh
homeboy component projects <id>
```

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

### `shared`

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

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

```sh
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](../architecture/output-system.md). The object below is the `data` payload.

`homeboy component` returns a `ComponentOutput` object.

```json
{
  "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": []
}
```

Notes:

- 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](build.md)
- [deploy](deploy.md)
- [fleet](fleet.md)
- [project](project.md)
- [JSON output contract](../architecture/output-system.md)
