Tasks

The hirotm tasks commands list, show by id, create, and change work items on a board: filterable listing, fetch one task by global id, add a card, edit fields, move it to another column, or send it through Trash (delete → restore or purge). Global options and output modes: hirotm CLI. You need the right CLI permissions on each board—see CLI access policy. Use hirotm boards describe and Lists to look up board slugs, list ids, and group ids. For shared flags (--profile, --client-name), see hirotm CLI. Access policy Turn on the toggles your workflow needs in Board settings. If the CLI is not allowed to do something, the command fails with an error message. For how Trash fits together, see the Trash: delete, restore, and purge section in Concepts.

Task Operations

`tasks list`

List tasks on a board. --board is required. Optional flags limit by column, group, priority, workflow status, release, or date range (same filters as the former boards tasks command).

Option	Type	Description
`--board <id-or-slug>`	string	Board id or slug.
`--list <id>`	integer	Only tasks in that column (list).
`--group <id>`	integer	Only tasks in that group (repeat the flag or use commas).
`--priority <id>`	integer	Only tasks with that priority (repeat or commas).
`--status <id>`	string	Only tasks in that workflow status (repeat or commas).
`--release-id <id>`	integer	Only tasks in those releases (repeat or commas; combined with OR).
`--untagged`	flag	Include tasks with no release (used together with `--release-id` as OR).
`--date-mode <mode>`	string	`opened`, `closed`, or `any`.
`--from <yyyy-mm-dd>`	string	Start of date range (inclusive).
`--to <yyyy-mm-dd>`	string	End of date range (inclusive).
`--limit <n>`	integer	Page size after server-side sort/filter (omit for one full response).
`--offset <n>`	integer	Skip this many tasks (default 0).
`--page-all`	flag	Merge all pages (`--limit` or 500 per request).
`--count-only`	flag	Print total matches only (Paging); not with `--limit`, `--offset`, `--page-all`, or `--fields`.
`--fields <keys>`	string	Comma-separated API keys per row. Allowed: `taskId`, `boardId`, `boardSlug`, `listId`, `title`, `body`, `groupId`, `priorityId`, `status`, `order`, `color`, `emoji`, `createdAt`, `updatedAt`, `closedAt`, `createdByPrincipal`, `createdByLabel`, `releaseId`. See Field projection.

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

hirotm tasks list --board sprint
hirotm tasks list --board sprint --list 3 --status open
hirotm tasks list --board sprint --release-id 1 --untagged
hirotm tasks list --board sprint --limit 100 --offset 200
hirotm tasks list --board sprint --page-all --limit 250
hirotm tasks list --board sprint --count-only
hirotm tasks list --board sprint --fields taskId,title,listId,status
hirotm tasks list --board sprint --profile dev              # non-default profile (optional)

Show Example list response

json

{"taskId":101,"boardId":1,"boardSlug":"sprint","listId":2,"groupId":1,"title":"Example","status":"open"}

(Real tasks include more fields from the API; sample abbreviated.)

`tasks show`

Print one task by global numeric id (GET /api/tasks/:taskId). The API resolves the board and applies readBoard for that board—no --board flag.

Option	Type	Required	Description
`<task-id>`	integer		Global task id.
`--fields <keys>`	string		Same allowlist as `tasks list` (see Field projection).

CLI examples

hirotm tasks show 101
hirotm tasks show 101 --fields taskId,title,status

`tasks add`

Create a task on a board. You must pass board, list (column), and group. The app fills in a default title if you skip --title.

Option	Type	Description
`--board <id-or-slug>`	string	Board id or slug.
`--list <id>`	integer	Column (list) id.
`--group <id>`	integer	Task group id.
`--title <text>`	string	Title (default Untitled).
`--status <id>`	string	Workflow status (default open).
`--priority <id>`	integer	Priority row id (omit for built-in none).
`--release <name-or-none>`	string	Release by exact name, or `none` for no release. Do not use together with `--release-id`.
`--release-id <id>`	integer	Release by id. Do not use together with `--release`. Omit both (with board defaults) to let the server auto-assign when that is enabled.
`--emoji <text>`	string	Emoji before the title.
`--clear-emoji`	flag	Store no emoji.
`--body <text>`	string	Body (Markdown).
`--body-file <path>`	string	Read body from a text file.
`--body-stdin`	flag	Read body from the terminal until input ends.

CLI Examples

hirotm tasks add --board sprint --list 2 --group 1 --title "Ship v1"
hirotm tasks add --board sprint --list 2 --group 1 --release none
hirotm tasks add --board sprint --list 2 --group 1 --title "Triage" --client-name "Cursor Agent"   # optional label last

AI Agent Examples

Add a task "Buy metro tickets" on board bucket-lists in list 2 and group 1.

Open in Cursor

Show Example responses

{
  "ok": true,
  "boardId": 1,
  "boardSlug": "sprint",
  "boardUpdatedAt": "2026-04-09T18:00:00.000Z",
  "entity": {
    "type": "task",
    "taskId": 101,
    "listId": 2,
    "groupId": 1,
    "priorityId": 0,
    "status": "open",
    "title": "Ship v1",
    "body": "",
    "color": null,
    "emoji": null,
    "createdAt": "2026-04-09T18:00:00.000Z",
    "updatedAt": "2026-04-09T18:00:00.000Z",
    "closedAt": null
  }
}

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

`tasks update`

Change any mix of fields on an existing task. The CLI resolves the board from the task id, so there is no --board flag. You must include at least one change flag.

Option	Type	Description
`<task-id>`	integer	Task id.
`--title <text>`	string	New title.
`--body <text>`	string	Body (Markdown).
`--body-file <path>`	string	Body from a text file.
`--body-stdin`	flag	Body from the terminal until input ends.
`--status <id>`	string	Workflow status id.
`--list <id>`	integer	Move to this list id (column).
`--group <id>`	integer	Task group id.
`--priority <id>`	integer	Priority row id (use built-in none id to reset).
`--release <name-or-none>`	string	Release by name, or `none`. Not with `--release-id`.
`--release-id <id>`	integer	Release by id. Not with `--release`.
`--color <css>`	string	Card color (CSS).
`--clear-color`	flag	Remove card color.
`--emoji <text>`	string	Emoji before the title.
`--clear-emoji`	flag	Remove emoji.

CLI Examples

hirotm tasks update --title "Ship v1.1" 101
hirotm tasks update --list 3 --group 1 101

AI Agent Examples

Set task 101 title to "Done when shipped".

Open in Cursor

Show Example responses

{
  "ok": true,
  "boardId": 1,
  "boardSlug": "sprint",
  "boardUpdatedAt": "2026-04-09T18:05:00.000Z",
  "entity": {
    "type": "task",
    "taskId": 101,
    "listId": 2,
    "groupId": 1,
    "priorityId": 0,
    "status": "open",
    "title": "Done when shipped",
    "body": "",
    "color": null,
    "emoji": null,
    "createdAt": "2026-04-09T18:00:00.000Z",
    "updatedAt": "2026-04-09T18:05:00.000Z",
    "closedAt": null
  }
}

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

`tasks move`

Move a task to another column (--to-list), optionally change its status in that column, and choose exactly one ordering hint: --first, --last, --before-task, or --after-task. The CLI resolves the board from the task id.

Option	Type	Description
`--to-list <id>`	integer	Destination column (list) id.
`<task-id>`	integer	Task id to move.
`--to-status <id>`	string	Status in the destination (omit to keep the current status).
`--before-task <id>`	integer	Place before this task in the destination band.
`--after-task <id>`	integer	Place after this task in the destination band.
`--first`	flag	First in the destination band.
`--last`	flag	Last in the destination band.

CLI Examples

hirotm tasks move --to-list 3 --first 101
hirotm tasks move --to-list 3 --after-task 99 101

AI Agent Examples

Move task 101 to list 3 at the top.

Open in Cursor

Show Example responses

{
  "ok": true,
  "boardId": 1,
  "boardSlug": "sprint",
  "boardUpdatedAt": "2026-04-09T18:10:00.000Z",
  "entity": {
    "type": "task",
    "taskId": 101,
    "listId": 3,
    "groupId": 1,
    "priorityId": 0,
    "status": "open",
    "title": "Ship v1",
    "body": "",
    "color": null,
    "emoji": null,
    "createdAt": "2026-04-09T18:00:00.000Z",
    "updatedAt": "2026-04-09T18:10:00.000Z",
    "closedAt": null
  }
}

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

`tasks delete`

Send a task to Trash. The CLI resolves the board from the task id for permission checks, confirmation text, and dry-run previews.

Option	Type	Description
`<task-id>`	integer	Task 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 tasks delete 101
hirotm tasks delete 101 --dry-run
hirotm tasks delete 101 --yes

AI Agent Examples

Move task 101 to Trash (non-interactive).

Open in Cursor

Show Example responses

{
  "ok": true,
  "boardId": 1,
  "boardSlug": "sprint",
  "boardUpdatedAt": "2026-04-09T18:15:00.000Z",
  "trashed": {
    "type": "task",
    "taskId": 101,
    "trashed": true
  }
}

{
  "error": "Task not found",
  "board": "sprint",
  "taskId": 101
}

`tasks restore`

Bring a task back from Trash. Only the task id is required (no board flag).

Option	Type	Required	Description
`<task-id>`	integer		Task id (see `hirotm trash list tasks` if unsure).
`-y`, `--yes`	flag		Skip the confirmation prompt.

CLI Examples

hirotm tasks restore 101
hirotm tasks restore 101 --yes

AI Agent Examples

Restore task 101 from Trash (non-interactive).

Open in Cursor

Show Example responses

{
  "ok": true,
  "boardId": 1,
  "boardSlug": "sprint",
  "boardUpdatedAt": "2026-04-09T18:20:00.000Z",
  "entity": {
    "type": "task",
    "taskId": 101,
    "listId": 2,
    "groupId": 1,
    "priorityId": 0,
    "status": "open",
    "title": "Ship v1",
    "body": "",
    "color": null,
    "emoji": null,
    "createdAt": "2026-04-09T18:00:00.000Z",
    "updatedAt": "2026-04-09T18:20:00.000Z",
    "closedAt": null
  }
}

{
  "error": "Task not found"
}

`tasks purge`

Remove a task from Trash permanently. Cannot be undone. Only the task id is required.

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

CLI Examples

hirotm tasks purge 101
hirotm tasks purge 101 --dry-run
hirotm tasks purge 101 --yes

AI Agent Examples

Permanently delete task 101 from Trash (non-interactive).

Open in Cursor

Show Example responses

{
  "ok": true,
  "purged": {
    "type": "task",
    "taskId": 101
  }
}

{
  "error": "Task not found"
}

Learn more

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

Get Started

CLI

Hiro Developers

Task Operations

`tasks list`

`tasks show`

`tasks add`

`tasks update`

`tasks move`

`tasks delete`

`tasks restore`

`tasks purge`

Learn more

​Task Operations

​tasks list

​tasks show

​tasks add

​tasks update

​tasks move

​tasks delete

​tasks restore

​tasks purge

​Learn more

Task Operations

`tasks list`

`tasks show`

`tasks add`

`tasks update`

`tasks move`

`tasks delete`

`tasks restore`

`tasks purge`

Learn more