Lists

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. 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. For board ids and slugs, see Boards. For tasks in those columns, see Tasks. For other hirotm commands, see hirotm CLI. 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.

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 lists (default 0).
`--page-all`	flag	Merge all pages (`--limit` or 500 per request).
`--count-only`	flag	Total lists only (Paging); not with `--limit`, `--offset`, `--page-all`, or `--fields`.
`--fields <keys>`	string	Comma-separated API keys per row. Allowed: `listId`, `boardId`, `boardSlug`, `name`, `order`, `color`, `emoji`, `createdByPrincipal`, `createdByLabel`. See Field projection.

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

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

List all lists on board sprint.

Open in Cursor

Show Example responses

{
  "listId": 1,
  "boardId": 1,
  "boardSlug": "sprint",
  "name": "Ready",
  "order": 0,
  "color": "#22c55e",
  "emoji": null,
  "createdByPrincipal": "web",
  "createdByLabel": null
}

{
  "error": "Board not found",
  "board": "unknown"
}

`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>`	integer		Global list id.
`--fields <keys>`	string		Same allowlist as `lists list`.

CLI examples

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	Description
`--board <id-or-slug>`	string	Board id or slug.
`[name]`	string	List name; omit to use the server default.
`--emoji <text>`	string	Optional emoji shown before the list name.

CLI Examples

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

Add a list "Paris Trip" to board bucket-lists.

Open in Cursor

Show Example responses

{
  "ok": true,
  "boardId": 1,
  "boardSlug": "sprint",
  "boardUpdatedAt": "2026-04-09T14:22:10.000Z",
  "entity": {
    "type": "list",
    "listId": 42,
    "name": "Ready",
    "order": 3,
    "emoji": null
  }
}

{
  "error": "Board not found",
  "board": "unknown-board"
}

`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	Description
`<list-id>`	integer	Numeric list id (from `hirotm boards describe` or task/board APIs).
`--name <text>`	string	New list name.
`--color <css>`	string	List color as CSS (for example a hex value).
`--clear-color`	flag	Remove the list color.
`--emoji <text>`	string	Emoji before the list name.
`--clear-emoji`	flag	Remove the list emoji.

CLI Examples

hirotm lists update --name "In review" 12
hirotm lists update --color "#3b82f6" 12
hirotm lists update --clear-color 12

AI Agent Examples

Rename list 12 to "QA".

Open in Cursor

Show Example responses

{
  "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
  }
}

{
  "error": "At least one update field is required"
}

`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	Description
`<list-id>`	integer	Numeric list id of the list to move.
`--before <list-id>`	integer	Place before another list.
`--after <list-id>`	integer	Place after another list.
`--first`	flag	Move to the first position.
`--last`	flag	Move to the last position.

CLI Examples

hirotm lists move --first 5
hirotm lists move --after 3 5
hirotm lists move --before 8 5 --client-name "Board tidy"

AI Agent Examples

Move list 5 to the first column.

Open in Cursor

Show Example responses

{
  "ok": true,
  "boardId": 1,
  "boardSlug": "sprint",
  "boardUpdatedAt": "2026-04-09T14:40:00.000Z",
  "entity": {
    "type": "list",
    "listId": 5,
    "name": "Doing",
    "order": 0,
    "emoji": null
  }
}

{
  "error": "Use only one of --before, --after, --first, or --last"
}

`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	Description
`<list-id>`	integer	Numeric list id.
`--dry-run`	flag	Preview only; do not move to Trash. See Dry-run preview.
`-y`, `--yes`	flag	Skip the confirmation prompt.

CLI Examples

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

Move list 12 to Trash (non-interactive).

Open in Cursor

Show Example responses

{
  "ok": true,
  "boardId": 1,
  "boardSlug": "sprint",
  "boardUpdatedAt": "2026-04-09T14:30:00.000Z",
  "trashed": {
    "type": "list",
    "listId": 12,
    "trashed": true
  }
}

{
  "error": "List not found",
  "board": "sprint",
  "listId": 12
}

`lists restore`

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

Option	Type	Required	Description
`<list-id>`	integer		Numeric list id (see `hirotm trash list lists`).
`-y`, `--yes`	flag		Skip the confirmation prompt.

CLI Examples

hirotm lists restore 12 --client-name "Undo mistake"
hirotm lists restore 12 --yes --client-name "Undo mistake"

AI Agent Examples

Restore list 12 from Trash (non-interactive).

Open in Cursor

Show Example responses

{
  "ok": true,
  "boardId": 1,
  "boardSlug": "sprint",
  "boardUpdatedAt": "2026-04-09T14:35:00.000Z",
  "entity": {
    "type": "list",
    "listId": 12,
    "name": "Ready",
    "order": 2,
    "emoji": null
  }
}

{
  "error": "List not found"
}

`lists purge`

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

Option	Type	Description
`<list-id>`	integer	Numeric list id.
`--dry-run`	flag	Preview only; do not purge. See Dry-run preview.
`-y`, `--yes`	flag	Skip the confirmation prompt.

CLI Examples

hirotm lists purge 12
hirotm lists purge 12 --dry-run
hirotm lists purge 12 --yes

AI Agent Examples

Permanently delete list 12 from Trash (non-interactive).

Open in Cursor

Show Example responses

{
  "ok": true,
  "purged": {
    "type": "list",
    "listId": 12
  }
}

{
  "error": "List not found"
}

Learn more

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

Get Started

CLI

Hiro Developers

`lists list`

`lists show`

`lists add`

`lists update`

`lists move`

`lists delete`

`lists restore`

`lists purge`

Learn more

​lists list

​lists show

​lists add

​lists update

​lists move

​lists delete

​lists restore

​lists purge

​Learn more

`lists list`

`lists show`

`lists add`

`lists update`

`lists move`

`lists delete`

`lists restore`

`lists purge`

Learn more