> ## 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.

# Lists

> Create and manage lists on Hiro Task Manager boards using the hirotm CLI.

The **`hirotm lists`** command group lists, shows one list by id, creates, and updates **lists** (columns) on a board. Global options and output modes: [hirotm CLI](/task-manager/cli/cli-commands). **`lists list`** needs **`readBoard`** on that board; **`lists show`** resolves the board from the list id and still requires **`readBoard`** on that board; writes need the appropriate flags from [CLI access policy](/task-manager/cli/cli-access-policy).

For board ids and slugs, see [Boards](/task-manager/cli/boards). For tasks in those columns, see [Tasks](/task-manager/cli/tasks). For other `hirotm` commands, see [hirotm CLI](/task-manager/cli/cli-commands).

**Access policy**

If the CLI is not allowed to read or change something, the command fails with an error message.

***

## `lists list`

List all lists on a board with full row fields from the API.

**Sort:** **`order`** ascending, then **`listId`** ascending (same column order as the board UI). 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 lists (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 lists 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: `listId`, `boardId`, `boardSlug`, `name`, `order`, `color`, `emoji`, `createdByPrincipal`, `createdByLabel`. See [Field projection](/task-manager/cli/cli-commands#field-projection). |

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

**CLI Examples**

```bash theme={null}
hirotm lists list --board sprint
hirotm lists list --board sprint --count-only
hirotm lists list --board sprint --limit 20 --offset 0
hirotm lists list --board sprint --page-all
hirotm lists list --board sprint --fields listId,name,order
```

**AI Agent Examples**

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

<Expandable title="Example responses" defaultOpen={false}>
  <CodeGroup>
    ```json json theme={null}
    {
      "listId": 1,
      "boardId": 1,
      "boardSlug": "sprint",
      "name": "Ready",
      "order": 0,
      "color": "#22c55e",
      "emoji": null,
      "createdByPrincipal": "web",
      "createdByLabel": null
    }
    ```

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

***

## `lists show`

Print one list by **global numeric id** (`GET /api/lists/:listId`). The API resolves the board and applies **`readBoard`** for that board—no **`--board`** flag.

| Option            | Type                                            | Required                                      | Description                         |
| ----------------- | ----------------------------------------------- | --------------------------------------------- | ----------------------------------- |
| `<list-id>`       | <Badge size="sm" color="purple">integer</Badge> | <Icon icon="check" color="green" size={14} /> | Global list id.                     |
| `--fields <keys>` | <Badge size="sm" color="blue">string</Badge>    | <Icon icon="minus" size={14} />               | Same allowlist as **`lists list`**. |

**CLI examples**

```bash theme={null}
hirotm lists show 3
hirotm lists show 3 --fields listId,name,order
```

***

## `lists add`

Create a list on a board. New lists are appended at the end unless you reorder with **`lists move`**.

| 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]`               | <Badge size="sm" color="blue">string</Badge> | <Icon icon="minus" size={14} />               | List name; omit to use the server default. |
| `--emoji <text>`       | <Badge size="sm" color="blue">string</Badge> | <Icon icon="minus" size={14} />               | Optional emoji shown before the list name. |

**CLI Examples**

```bash theme={null}
hirotm lists add --board sprint "Ready"
hirotm lists add --board sprint --emoji "🚀" "Launch"
hirotm lists add --board sprint "Hotfix" --client-name "Deploy script"   # writer label last
```

**AI Agent Examples**

<Prompt description="Add a list &#x22;Paris Trip&#x22; to board bucket-lists." actions={["copy", "cursor"]}>
  Add a list "Paris Trip" to board bucket-lists.
</Prompt>

<Expandable title="Example responses" defaultOpen={false}>
  <CodeGroup>
    ```json json theme={null}
    {
      "ok": true,
      "boardId": 1,
      "boardSlug": "sprint",
      "boardUpdatedAt": "2026-04-09T14:22:10.000Z",
      "entity": {
        "type": "list",
        "listId": 42,
        "name": "Ready",
        "order": 3,
        "emoji": null
      }
    }
    ```

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

***

## `lists update`

Patch fields on a list. The CLI resolves the board from the list id, so there is no **`--board`** flag. At least one of **`--name`**, **`--color`**, **`--clear-color`**, **`--emoji`**, or **`--clear-emoji`** must be present.

| Option           | Type                                            | Required                                      | Description                                                             |
| ---------------- | ----------------------------------------------- | --------------------------------------------- | ----------------------------------------------------------------------- |
| `<list-id>`      | <Badge size="sm" color="purple">integer</Badge> | <Icon icon="check" color="green" size={14} /> | Numeric list id (from **`hirotm boards describe`** or task/board APIs). |
| `--name <text>`  | <Badge size="sm" color="blue">string</Badge>    | <Icon icon="minus" size={14} />               | New list name.                                                          |
| `--color <css>`  | <Badge size="sm" color="blue">string</Badge>    | <Icon icon="minus" size={14} />               | List color as CSS (for example a hex value).                            |
| `--clear-color`  | <Badge size="sm" color="orange">flag</Badge>    | <Icon icon="minus" size={14} />               | Remove the list color.                                                  |
| `--emoji <text>` | <Badge size="sm" color="blue">string</Badge>    | <Icon icon="minus" size={14} />               | Emoji before the list name.                                             |
| `--clear-emoji`  | <Badge size="sm" color="orange">flag</Badge>    | <Icon icon="minus" size={14} />               | Remove the list emoji.                                                  |

**CLI Examples**

```bash theme={null}
hirotm lists update --name "In review" 12
hirotm lists update --color "#3b82f6" 12
hirotm lists update --clear-color 12
```

**AI Agent Examples**

<Prompt description="Rename list 12 to &#x22;QA&#x22;." actions={["copy", "cursor"]}>
  Rename list 12 to "QA".
</Prompt>

<Expandable title="Example responses" defaultOpen={false}>
  <CodeGroup>
    ```json json theme={null}
    {
      "ok": true,
      "boardId": 1,
      "boardSlug": "sprint",
      "boardUpdatedAt": "2026-04-09T14:25:00.000Z",
      "entity": {
        "type": "list",
        "listId": 12,
        "name": "In review",
        "order": 1,
        "color": "#3b82f6",
        "emoji": null
      }
    }
    ```

    ```json error theme={null}
    {
      "error": "At least one update field is required"
    }
    ```
  </CodeGroup>
</Expandable>

***

## `lists move`

Change list order on a board. The CLI resolves the board from the list id. Use **exactly one** of **`--before`**, **`--after`**, **`--first`**, or **`--last`** (the CLI rejects multiple placement flags).

| Option               | Type                                            | Required                                      | Description                          |
| -------------------- | ----------------------------------------------- | --------------------------------------------- | ------------------------------------ |
| `<list-id>`          | <Badge size="sm" color="purple">integer</Badge> | <Icon icon="check" color="green" size={14} /> | Numeric list id of the list to move. |
| `--before <list-id>` | <Badge size="sm" color="purple">integer</Badge> | <Icon icon="minus" size={14} />               | Place before another list.           |
| `--after <list-id>`  | <Badge size="sm" color="purple">integer</Badge> | <Icon icon="minus" size={14} />               | Place after another list.            |
| `--first`            | <Badge size="sm" color="orange">flag</Badge>    | <Icon icon="minus" size={14} />               | Move to the first position.          |
| `--last`             | <Badge size="sm" color="orange">flag</Badge>    | <Icon icon="minus" size={14} />               | Move to the last position.           |

**CLI Examples**

```bash theme={null}
hirotm lists move --first 5
hirotm lists move --after 3 5
hirotm lists move --before 8 5 --client-name "Board tidy"
```

**AI Agent Examples**

<Prompt description="Move list 5 to the first column." actions={["copy", "cursor"]}>
  Move list 5 to the first column.
</Prompt>

<Expandable title="Example responses" defaultOpen={false}>
  <CodeGroup>
    ```json json theme={null}
    {
      "ok": true,
      "boardId": 1,
      "boardSlug": "sprint",
      "boardUpdatedAt": "2026-04-09T14:40:00.000Z",
      "entity": {
        "type": "list",
        "listId": 5,
        "name": "Doing",
        "order": 0,
        "emoji": null
      }
    }
    ```

    ```json error theme={null}
    {
      "error": "Use only one of --before, --after, --first, or --last"
    }
    ```
  </CodeGroup>
</Expandable>

***

## `lists delete`

Move a list to **Trash**. The CLI resolves the board from the list id for permission checks, confirmation text, and dry-run previews. Restore or purge with **`lists restore`** / **`lists purge`** using the same numeric list id (see **`hirotm trash list lists`** for context).

| Option        | Type                                            | Required                                      | Description                                                                                                |
| ------------- | ----------------------------------------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `<list-id>`   | <Badge size="sm" color="purple">integer</Badge> | <Icon icon="check" color="green" size={14} /> | Numeric list id.                                                                                           |
| `--dry-run`   | <Badge size="sm" color="orange">flag</Badge>    | <Icon icon="minus" size={14} />               | Preview only; do not move to Trash. See [Dry-run preview](/task-manager/cli/cli-commands#dry-run-preview). |
| `-y`, `--yes` | <Badge size="sm" color="orange">flag</Badge>    | <Icon icon="minus" size={14} />               | Skip the confirmation prompt.                                                                              |

**CLI Examples**

```bash theme={null}
hirotm lists delete 12 --dry-run
hirotm lists delete 12 --client-name "Cleanup job"
hirotm lists delete 12 --yes --client-name "Cleanup job"
```

**AI Agent Examples**

<Prompt description="Move list 12 to Trash (non-interactive)." actions={["copy", "cursor"]}>
  hirotm lists delete 12 --yes --client-name "Cursor Agent"
</Prompt>

<Expandable title="Example responses" defaultOpen={false}>
  <CodeGroup>
    ```json json theme={null}
    {
      "ok": true,
      "boardId": 1,
      "boardSlug": "sprint",
      "boardUpdatedAt": "2026-04-09T14:30:00.000Z",
      "trashed": {
        "type": "list",
        "listId": 12,
        "trashed": true
      }
    }
    ```

    ```json error theme={null}
    {
      "error": "List not found",
      "board": "sprint",
      "listId": 12
    }
    ```
  </CodeGroup>
</Expandable>

***

## `lists restore`

Restore a list from Trash. The board must still be active (not in Trash).

| Option        | Type                                            | Required                                      | Description                                          |
| ------------- | ----------------------------------------------- | --------------------------------------------- | ---------------------------------------------------- |
| `<list-id>`   | <Badge size="sm" color="purple">integer</Badge> | <Icon icon="check" color="green" size={14} /> | Numeric list id (see **`hirotm trash list lists`**). |
| `-y`, `--yes` | <Badge size="sm" color="orange">flag</Badge>    | <Icon icon="minus" size={14} />               | Skip the confirmation prompt.                        |

**CLI Examples**

```bash theme={null}
hirotm lists restore 12 --client-name "Undo mistake"
hirotm lists restore 12 --yes --client-name "Undo mistake"
```

**AI Agent Examples**

<Prompt description="Restore list 12 from Trash (non-interactive)." actions={["copy", "cursor"]}>
  hirotm lists restore 12 --yes --client-name "Cursor Agent"
</Prompt>

<Expandable title="Example responses" defaultOpen={false}>
  <CodeGroup>
    ```json json theme={null}
    {
      "ok": true,
      "boardId": 1,
      "boardSlug": "sprint",
      "boardUpdatedAt": "2026-04-09T14:35:00.000Z",
      "entity": {
        "type": "list",
        "listId": 12,
        "name": "Ready",
        "order": 2,
        "emoji": null
      }
    }
    ```

    ```json error theme={null}
    {
      "error": "List not found"
    }
    ```
  </CodeGroup>
</Expandable>

***

## `lists purge`

Permanently delete a list that is already in Trash. This cannot be undone.

| Option        | Type                                            | Required                                      | Description                                                                                        |
| ------------- | ----------------------------------------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `<list-id>`   | <Badge size="sm" color="purple">integer</Badge> | <Icon icon="check" color="green" size={14} /> | Numeric list id.                                                                                   |
| `--dry-run`   | <Badge size="sm" color="orange">flag</Badge>    | <Icon icon="minus" size={14} />               | Preview only; do not purge. See [Dry-run preview](/task-manager/cli/cli-commands#dry-run-preview). |
| `-y`, `--yes` | <Badge size="sm" color="orange">flag</Badge>    | <Icon icon="minus" size={14} />               | Skip the confirmation prompt.                                                                      |

**CLI Examples**

```bash theme={null}
hirotm lists purge 12
hirotm lists purge 12 --dry-run
hirotm lists purge 12 --yes
```

**AI Agent Examples**

<Prompt description="Permanently delete list 12 from Trash (non-interactive)." actions={["copy", "cursor"]}>
  hirotm lists purge 12 --yes
</Prompt>

<Expandable title="Example responses" defaultOpen={false}>
  <CodeGroup>
    ```json json theme={null}
    {
      "ok": true,
      "purged": {
        "type": "list",
        "listId": 12
      }
    }
    ```

    ```json error theme={null}
    {
      "error": "List not found"
    }
    ```
  </CodeGroup>
</Expandable>

***

## Learn more

Run **`hirotm help lists`** or **`hirotm help lists <subcommand>`** for the exact help text shipped with your CLI version.