Synopsis

homeboy changelog [COMMAND]

Description

homeboy changelog prints the embedded Homeboy CLI changelog documentation (from docs/changelog.md) as raw markdown by default.

In JSON output mode, the default show output is returned as JSON (with a content field containing the markdown).

Subcommands

Default (show)

homeboy changelog
homeboy changelog --self

Shows the embedded Homeboy CLI changelog documentation (from docs/changelog.md).

Options:

• --self: Show Homeboy’s own changelog (release notes) instead of a component’s changelog

This prints raw markdown to stdout.

add

homeboy changelog add <component_id> <message>
homeboy changelog add <component_id> -m "first" -m "second"
homeboy changelog add <component_id> -m "Bug fix" --type fixed
homeboy changelog add <component_id> -m "New feature" -t added
homeboy changelog add --json <spec>

Options:

• -m, --message <message>: Changelog message (repeatable)
• -t, --type <type>: Changelog subsection type for Keep a Changelog format. Valid values: added, changed, deprecated, removed, fixed, security (case-insensitive)

Notes:

• The changelog entry is the positional <message> value. Use --json for multiple messages in one run.
• Changelog messages are intended to be user-facing release notes (capture anything impacting user or developer experience), not a 1:1 copy of commit subjects.
• When --json is provided, other args are ignored and the payload’s messages array is applied in order.
• When --type is provided, items are placed under the corresponding Keep a Changelog subsection (e.g., ### Fixed). If the subsection doesn’t exist, it’s created in canonical order.

init

homeboy changelog init <component_id>
homeboy changelog init <component_id> --path "docs/CHANGELOG.md"
homeboy changelog init <component_id> --configure

Creates a new changelog file with the Keep a Changelog format (## [X.Y.Z] - YYYY-MM-DD).

Options:

• --path <path>: Custom path for changelog file (relative to component). Default: CHANGELOG.md
• --configure: Also update component config to add changelog_target

Requirements:

• Component must have version_targets configured (to determine initial version)
• Errors if changelog file already exists at target path

Prerequisites

Before using changelog add, configure the changelog path:

homeboy component set <id> --changelog-target "CHANGELOG.md"

This is required for both changelog add and version bump.

Changelog Resolution

For add, Homeboy resolves the changelog from the component’s changelog_target configuration.

Adds one or more changelog items to the configured "next" section in the component’s changelog file.

--json for this command is an add subcommand option (not a root/global flag).

Configuration / defaults (strict by default):

• Changelog path resolution:
  • If changelog_target is set in the component config, that path is used (relative to component.local_path unless it’s absolute).
  • If changelog_target is not configured, the command errors with instructions to set it.
• "Next section" resolution:
  • If no label is configured, Homeboy defaults to Unreleased.
  • If no aliases are configured, Homeboy matches both Unreleased and [Unreleased].
  • If aliases are configured, Homeboy ensures the label and bracketed label are included for matching.
  • Config overrides (most specific first): component config → project config → defaults.

Notes:

• If changelog_target is set in the component config, that path is used (relative to component.local_path unless it’s absolute).
• If changelog_target is not configured, the command errors with instructions to set it.

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.

• If no label is configured, Homeboy defaults to Unreleased.
• If no aliases are configured, Homeboy matches both Unreleased and [Unreleased].
• If aliases are configured, Homeboy ensures the label and bracketed label are included for matching.
• Config overrides (most specific first): component config → project config → defaults.

JSON output (default)

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": "show",
  "topic_label": "changelog",
  "content": "<markdown content>"
}

JSON output (add)

{
  "command": "add",
  "component_id": "<component_id>",
  "changelog_path": "<absolute/or/resolved/path.md>",
  "next_section_label": "<label>",
  "messages": ["<message>", "<message>"],
  "items_added": 2,
  "changed": true,
  "subsection_type": "fixed"
}

homeboy changelog returns a tagged union:

This section applies only when JSON output is used.

{ "component_id": "<component_id>", "messages": ["<message>"] }

JSON output (init)

{
  "command": "init",
  "component_id": "<component_id>",
  "changelog_path": "<absolute/path/to/CHANGELOG.md>",
  "initial_version": "0.3.2",
  "next_section_label": "Unreleased",
  "created": true,
  "configured": false
}

Errors

• If changelog_target is set in the component config, that path is used (relative to component.local_path unless it’s absolute).
• If changelog_target is not configured, the command errors with instructions to set it.

Related

• If no label is configured, Homeboy defaults to Unreleased.
• If no aliases are configured, Homeboy matches both Unreleased and [Unreleased].
• If aliases are configured, Homeboy ensures the label and bracketed label are included for matching.
• Config overrides (most specific first): component config → project config → defaults.