Releases

Releases are labels on a board used to group tasks (for example milestones or versions). The hirotm releases commands list them, show one, create or edit them, set which release is the board default for new tasks, or remove them. Global options and output modes: hirotm CLI. Listing and show need readBoard on that board. Add, update, set-default, and delete need manageStructure—see CLI access policy. Use Boards for board slugs and ids. Task commands use releases when you set --release or --release-id—see Tasks. For shared flags (--profile, --client-name), see hirotm CLI. Access policy If the CLI is not allowed to do something, the command fails with an error message.

Release operations

`releases list`

List releases on the chosen board. Sort: created time ascending, then releaseId ascending (oldest release first). See Default sort order.

Option	Type	Description
`--board <id-or-slug>`	string	Board id or slug.
`--limit <n>`	integer	Page size (omit for one full response).
`--offset <n>`	integer	Skip this many releases (default 0).
`--page-all`	flag	Merge all pages (`--limit` or 500 per request).
`--count-only`	flag	Total releases only (Paging); not with `--limit`, `--offset`, `--page-all`, or `--fields`.
`--fields <keys>`	string	Comma-separated API keys per row. Allowed: `releaseId`, `name`, `color`, `releaseDate`, `createdAt`. See Field projection.

Accepts global -q / --quiet (with --format ndjson); default field releaseId. See Pipe-friendly quiet. CLI Examples

hirotm releases list --board sprint
hirotm releases list --board sprint --count-only
hirotm releases list --board sprint --limit 20 --offset 0
hirotm releases list --board sprint --page-all
hirotm releases list --board sprint --fields releaseId,name,releaseDate

AI Agent Examples

List all releases on board sprint.

Open in Cursor

Show Example responses

{
  "items": [
    {
      "releaseId": 1,
      "name": "v1.0",
      "color": "#3b82f6",
      "releaseDate": "2026-06-01",
      "createdAt": "2026-04-01T12:00:00.000Z"
    }
  ],
  "total": 1,
  "limit": 1,
  "offset": 0
}

`releases show`

Print one release by id. The CLI loads the board’s releases (following pagination on the API as needed) and picks the matching id (same result shape as a single element inside releases list’s items).

Option	Type	Description
`--board <id-or-slug>`	string	Board id or slug.
`<release-id>`	integer	Release id.
`--fields <keys>`	string	Comma-separated API keys on the printed release object. Allowed: `releaseId`, `name`, `color`, `releaseDate`, `createdAt`. See Field projection.

CLI Examples

hirotm releases show --board sprint 1
hirotm releases show --board sprint --fields releaseId,name,color 1

AI Agent Examples

Show release 1 on board sprint.

Open in Cursor

Show Example responses

{
  "releaseId": 1,
  "name": "v1.0",
  "color": "#3b82f6",
  "releaseDate": "2026-06-01",
  "createdAt": "2026-04-01T12:00:00.000Z"
}

`releases add`

Create a release. The name must be unique on that board. If that name is already taken, the API returns 409 Conflict; hirotm then exits 5 with code: conflict on stderr (see Errors & exit codes). The error text is A release with this name already exists on this board.

Option	Type	Description
`--board <id-or-slug>`	string	Board id or slug.
`--name <text>`	string	Release name (unique per board).
`--color <css>`	string	Optional color (CSS).
`--clear-color`	flag	Create with no color.
`--release-date <text>`	string	Optional date label (for example YYYY-MM-DD).
`--clear-release-date`	flag	No release date.

CLI Examples

hirotm releases add --board sprint --name "v2.0" --release-date 2026-07-01

AI Agent Examples

Add release "Hotfix May" on board sprint with no date.

Open in Cursor

Show Example responses

{
  "releaseId": 2,
  "name": "Hotfix May",
  "color": null,
  "releaseDate": null,
  "createdAt": "2026-04-09T20:00:00.000Z"
}

`releases update`

Change name, color, and/or release date. At least one change flag is required. Renaming to a name that already exists on the board returns 409 (same conflict / exit 5 behavior as releases add). If the release id does not exist on that board, the API returns 404 (not_found / exit 3).

Option	Type	Description
`--board <id-or-slug>`	string	Board id or slug.
`<release-id>`	integer	Release id.
`--name <text>`	string	New name.
`--color <css>`	string	Color (CSS).
`--clear-color`	flag	Remove color.
`--release-date <text>`	string	Release date.
`--clear-release-date`	flag	Clear release date.

CLI Examples

hirotm releases update --board sprint --name "v1.0 GA" 1

AI Agent Examples

Rename release 2 on board sprint to v2.0 beta.

Open in Cursor

Show Example responses

{
  "releaseId": 1,
  "name": "v1.0 GA",
  "color": "#3b82f6",
  "releaseDate": "2026-06-01",
  "createdAt": "2026-04-01T12:00:00.000Z"
}

`releases set-default`

Set or clear the board’s default release (defaultReleaseId). That is the release used when the board’s auto-assign rules apply and a new task is created without an explicit release. The CLI issues PATCH /api/boards/:id (not the releases sub-resource). If you pass a <release-id>, the CLI checks it exists on the board before PATCHing; otherwise you get Release not found (exit 3) instead of a generic 404. Do not pass <release-id> together with --clear.

Option / argument	Type	Description
`--board <id-or-slug>`	string	Board id or slug.
`<release-id>`	integer	Release id to use as the default (omit when using `--clear`).
`--clear`	flag	Clear the board default release.

CLI Examples

hirotm releases set-default --board sprint 1
hirotm releases set-default --board sprint --clear

AI Agent Examples

Set the board default release to release 2 on board sprint (non-interactive).

Open in Cursor

Show Example responses

{
  "ok": true,
  "boardId": 1,
  "boardSlug": "sprint",
  "boardUpdatedAt": "2026-04-01T12:00:00.000Z",
  "entity": {
    "type": "board",
    "boardId": 1,
    "slug": "sprint",
    "name": "Sprint",
    "emoji": null,
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-04-01T12:00:00.000Z",
    "defaultReleaseId": 1
  }
}

`releases delete`

Remove a release. Tasks on that release become untagged unless you pass --move-tasks-to with another release id on the same board.

Option	Type	Description
`--board <id-or-slug>`	string	Board id or slug.
`<release-id>`	integer	Release id to delete.
`--move-tasks-to <id>`	integer	Move tasks to this release id before deleting.
`-y`, `--yes`	flag	Skip the confirmation prompt.

CLI Examples

hirotm releases delete --board sprint 2
hirotm releases delete --board sprint --move-tasks-to 1 2 --yes

AI Agent Examples

Delete release 3 on board sprint; move tasks to release 1 (non-interactive).

Open in Cursor

Show Example responses

{
  "ok": true,
  "board": "sprint",
  "deletedReleaseId": 3
}

Learn more

Run hirotm help releases or hirotm help releases <subcommand> for the full help text in your installed CLI.

Get Started

CLI

Hiro Developers

Release operations

`releases list`

`releases show`

`releases add`

`releases update`

`releases set-default`

`releases delete`

Learn more

Get Started

CLI

Hiro Developers

​Release operations

​releases list

​releases show

​releases add

​releases update

​releases set-default

​releases delete

​Learn more

Release operations

`releases list`

`releases show`

`releases add`

`releases update`

`releases set-default`

`releases delete`

Learn more