> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hiroleague.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Releases

> List and manage board releases with the `hirotm` CLI.

**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](/task-manager/cli/cli-commands).

**Listing** and **show** need **`readBoard`** on that board. **Add**, **update**, **set-default**, and **delete** need **`manageStructure`**—see [CLI access policy](/task-manager/cli/cli-access-policy).

Use [Boards](/task-manager/cli/boards) for board slugs and ids. Task commands use releases when you set **`--release`** or **`--release-id`**—see [Tasks](/task-manager/cli/tasks). For shared flags (**`--profile`**, **`--client-name`**), see [hirotm CLI](/task-manager/cli/cli-commands).

**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](/task-manager/cli/cli-commands#default-sort-order).

| Option                 | Type                                            | Required                                      | Description                                                                                                                                                                   |
| ---------------------- | ----------------------------------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--board <id-or-slug>` | <Badge size="sm" color="blue">string</Badge>    | <Icon icon="check" color="green" size={14} /> | Board id or slug.                                                                                                                                                             |
| `--limit <n>`          | <Badge size="sm" color="purple">integer</Badge> | <Icon icon="minus" size={14} />               | Page size (omit for one full response).                                                                                                                                       |
| `--offset <n>`         | <Badge size="sm" color="purple">integer</Badge> | <Icon icon="minus" size={14} />               | Skip this many releases (default **0**).                                                                                                                                      |
| `--page-all`           | <Badge size="sm" color="orange">flag</Badge>    | <Icon icon="minus" size={14} />               | Merge all pages (**`--limit`** or **500** per request).                                                                                                                       |
| `--count-only`         | <Badge size="sm" color="orange">flag</Badge>    | <Icon icon="minus" size={14} />               | Total releases only ([Paging](/task-manager/cli/cli-commands#paging-list-results)); not with **`--limit`**, **`--offset`**, **`--page-all`**, or **`--fields`**.              |
| `--fields <keys>`      | <Badge size="sm" color="blue">string</Badge>    | <Icon icon="minus" size={14} />               | Comma-separated API keys per row. Allowed: `releaseId`, `name`, `color`, `releaseDate`, `createdAt`. See [Field projection](/task-manager/cli/cli-commands#field-projection). |

Accepts global **`-q` / `--quiet`** (with **`--format ndjson`**); default field **`releaseId`**. See [Pipe-friendly quiet](/task-manager/cli/cli-commands#pipe-friendly-quiet).

**CLI Examples**

```bash theme={null}
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**

<Prompt description="List all releases on board sprint." actions={["copy", "cursor"]}>
  List all releases on board sprint.
</Prompt>

<Expandable title="Example responses" defaultOpen={false}>
  <CodeGroup>
    ```json json theme={null}
    {
      "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
    }
    ```

    ```json error theme={null}
    {
      "error": "Board not found",
      "board": "unknown"
    }
    ```
  </CodeGroup>
</Expandable>

***

### `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                                            | Required                                      | Description                                                                                                                                                                                         |
| ---------------------- | ----------------------------------------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--board <id-or-slug>` | <Badge size="sm" color="blue">string</Badge>    | <Icon icon="check" color="green" size={14} /> | Board id or slug.                                                                                                                                                                                   |
| `<release-id>`         | <Badge size="sm" color="purple">integer</Badge> | <Icon icon="check" color="green" size={14} /> | Release id.                                                                                                                                                                                         |
| `--fields <keys>`      | <Badge size="sm" color="blue">string</Badge>    | <Icon icon="minus" size={14} />               | Comma-separated API keys on the printed release object. Allowed: `releaseId`, `name`, `color`, `releaseDate`, `createdAt`. See [Field projection](/task-manager/cli/cli-commands#field-projection). |

**CLI Examples**

```bash theme={null}
hirotm releases show --board sprint 1
hirotm releases show --board sprint --fields releaseId,name,color 1
```

**AI Agent Examples**

<Prompt description="Show release 1 on board sprint." actions={["copy", "cursor"]}>
  Show release 1 on board sprint.
</Prompt>

<Expandable title="Example responses" defaultOpen={false}>
  <CodeGroup>
    ```json json theme={null}
    {
      "releaseId": 1,
      "name": "v1.0",
      "color": "#3b82f6",
      "releaseDate": "2026-06-01",
      "createdAt": "2026-04-01T12:00:00.000Z"
    }
    ```

    ```json error theme={null}
    {
      "error": "Release not found",
      "board": "sprint",
      "releaseId": 99
    }
    ```
  </CodeGroup>
</Expandable>

***

### `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](/task-manager/cli/error-codes)). The error text is *A release with this name already exists on this board.*

| Option                  | Type                                         | Required                                      | Description                                       |
| ----------------------- | -------------------------------------------- | --------------------------------------------- | ------------------------------------------------- |
| `--board <id-or-slug>`  | <Badge size="sm" color="blue">string</Badge> | <Icon icon="check" color="green" size={14} /> | Board id or slug.                                 |
| `--name <text>`         | <Badge size="sm" color="blue">string</Badge> | <Icon icon="check" color="green" size={14} /> | Release name (unique per board).                  |
| `--color <css>`         | <Badge size="sm" color="blue">string</Badge> | <Icon icon="minus" size={14} />               | Optional color (CSS).                             |
| `--clear-color`         | <Badge size="sm" color="orange">flag</Badge> | <Icon icon="minus" size={14} />               | Create with no color.                             |
| `--release-date <text>` | <Badge size="sm" color="blue">string</Badge> | <Icon icon="minus" size={14} />               | Optional date label (for example **YYYY-MM-DD**). |
| `--clear-release-date`  | <Badge size="sm" color="orange">flag</Badge> | <Icon icon="minus" size={14} />               | No release date.                                  |

**CLI Examples**

```bash theme={null}
hirotm releases add --board sprint --name "v2.0" --release-date 2026-07-01
```

**AI Agent Examples**

<Prompt description="Add release &#x22;Hotfix May&#x22; on board sprint with no date." actions={["copy", "cursor"]}>
  Add release "Hotfix May" on board sprint with no date.
</Prompt>

<Expandable title="Example responses" defaultOpen={false}>
  <CodeGroup>
    ```json json theme={null}
    {
      "releaseId": 2,
      "name": "Hotfix May",
      "color": null,
      "releaseDate": null,
      "createdAt": "2026-04-09T20:00:00.000Z"
    }
    ```

    ```json error theme={null}
    {
      "error": "Board not found",
      "board": "sprint"
    }
    ```

    ```json error theme={null}
    {
      "error": "A release with this name already exists on this board.",
      "code": "conflict",
      "status": 409
    }
    ```
  </CodeGroup>
</Expandable>

***

### `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                                            | Required                                      | Description         |
| ----------------------- | ----------------------------------------------- | --------------------------------------------- | ------------------- |
| `--board <id-or-slug>`  | <Badge size="sm" color="blue">string</Badge>    | <Icon icon="check" color="green" size={14} /> | Board id or slug.   |
| `<release-id>`          | <Badge size="sm" color="purple">integer</Badge> | <Icon icon="check" color="green" size={14} /> | Release id.         |
| `--name <text>`         | <Badge size="sm" color="blue">string</Badge>    | <Icon icon="minus" size={14} />               | New name.           |
| `--color <css>`         | <Badge size="sm" color="blue">string</Badge>    | <Icon icon="minus" size={14} />               | Color (CSS).        |
| `--clear-color`         | <Badge size="sm" color="orange">flag</Badge>    | <Icon icon="minus" size={14} />               | Remove color.       |
| `--release-date <text>` | <Badge size="sm" color="blue">string</Badge>    | <Icon icon="minus" size={14} />               | Release date.       |
| `--clear-release-date`  | <Badge size="sm" color="orange">flag</Badge>    | <Icon icon="minus" size={14} />               | Clear release date. |

**CLI Examples**

```bash theme={null}
hirotm releases update --board sprint --name "v1.0 GA" 1
```

**AI Agent Examples**

<Prompt description="Rename release 2 on board sprint to v2.0 beta." actions={["copy", "cursor"]}>
  Rename release 2 on board sprint to v2.0 beta.
</Prompt>

<Expandable title="Example responses" defaultOpen={false}>
  <CodeGroup>
    ```json json theme={null}
    {
      "releaseId": 1,
      "name": "v1.0 GA",
      "color": "#3b82f6",
      "releaseDate": "2026-06-01",
      "createdAt": "2026-04-01T12:00:00.000Z"
    }
    ```

    ```json error theme={null}
    {
      "error": "At least one update field is required"
    }
    ```

    ```json error theme={null}
    {
      "error": "Release not found",
      "code": "not_found",
      "status": 404
    }
    ```

    ```json error theme={null}
    {
      "error": "A release with this name already exists on this board.",
      "code": "conflict",
      "status": 409
    }
    ```
  </CodeGroup>
</Expandable>

***

### `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                                            | Required                                      | Description                                                       |
| ---------------------- | ----------------------------------------------- | --------------------------------------------- | ----------------------------------------------------------------- |
| `--board <id-or-slug>` | <Badge size="sm" color="blue">string</Badge>    | <Icon icon="check" color="green" size={14} /> | Board id or slug.                                                 |
| `<release-id>`         | <Badge size="sm" color="purple">integer</Badge> | <Icon icon="minus" size={14} />               | Release id to use as the default (omit when using **`--clear`**). |
| `--clear`              | <Badge size="sm" color="orange">flag</Badge>    | <Icon icon="minus" size={14} />               | Clear the board default release.                                  |

**CLI Examples**

```bash theme={null}
hirotm releases set-default --board sprint 1
hirotm releases set-default --board sprint --clear
```

**AI Agent Examples**

<Prompt description="Set the board default release to release 2 on board sprint (non-interactive)." actions={["copy", "cursor"]}>
  Set the board default release to release 2 on board sprint. Use `--client-name` on the command.
</Prompt>

<Expandable title="Example responses" defaultOpen={false}>
  <CodeGroup>
    ```json json theme={null}
    {
      "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
      }
    }
    ```

    ```json error theme={null}
    {
      "error": "Release not found",
      "board": "sprint",
      "releaseId": 99
    }
    ```
  </CodeGroup>
</Expandable>

***

### `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                                            | Required                                      | Description                                    |
| ---------------------- | ----------------------------------------------- | --------------------------------------------- | ---------------------------------------------- |
| `--board <id-or-slug>` | <Badge size="sm" color="blue">string</Badge>    | <Icon icon="check" color="green" size={14} /> | Board id or slug.                              |
| `<release-id>`         | <Badge size="sm" color="purple">integer</Badge> | <Icon icon="check" color="green" size={14} /> | Release id to delete.                          |
| `--move-tasks-to <id>` | <Badge size="sm" color="purple">integer</Badge> | <Icon icon="minus" size={14} />               | Move tasks to this release id before deleting. |
| `-y`, `--yes`          | <Badge size="sm" color="orange">flag</Badge>    | <Icon icon="minus" size={14} />               | Skip the confirmation prompt.                  |

**CLI Examples**

```bash theme={null}
hirotm releases delete --board sprint 2
hirotm releases delete --board sprint --move-tasks-to 1 2 --yes
```

**AI Agent Examples**

<Prompt description="Delete release 3 on board sprint; move tasks to release 1 (non-interactive)." actions={["copy", "cursor"]}>
  hirotm releases delete --board sprint --move-tasks-to 1 3 --yes
</Prompt>

<Expandable title="Example responses" defaultOpen={false}>
  <CodeGroup>
    ```json json theme={null}
    {
      "ok": true,
      "board": "sprint",
      "deletedReleaseId": 3
    }
    ```

    ```json error theme={null}
    {
      "error": "Board not found",
      "board": "unknown"
    }
    ```
  </CodeGroup>
</Expandable>

***

## Learn more

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