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

# Tasks

> Create, update, move, and manage Task Manager tasks with the `hirotm` CLI.

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

You need the right CLI permissions on each board—see [CLI access policy](/task-manager/cli/cli-access-policy). Use **`hirotm boards describe`** and [Lists](/task-manager/cli/lists) to look up **board** slugs, **list** ids, and **group** ids. For shared flags (**`--profile`**, **`--client-name`**), see [hirotm CLI](/task-manager/cli/cli-commands).

**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-manager/get-started/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                                            | Required                                      | Description                                                                                                                                                                                                                                                                                                                               |
| ---------------------- | ----------------------------------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--board <id-or-slug>` | <Badge size="sm" color="blue">string</Badge>    | <Icon icon="check" color="green" size={14} /> | Board id or slug.                                                                                                                                                                                                                                                                                                                         |
| `--list <id>`          | <Badge size="sm" color="purple">integer</Badge> | <Icon icon="minus" size={14} />               | Only tasks in that column (list).                                                                                                                                                                                                                                                                                                         |
| `--group <id>`         | <Badge size="sm" color="purple">integer</Badge> | <Icon icon="minus" size={14} />               | Only tasks in that group (repeat the flag or use commas).                                                                                                                                                                                                                                                                                 |
| `--priority <id>`      | <Badge size="sm" color="purple">integer</Badge> | <Icon icon="minus" size={14} />               | Only tasks with that priority (repeat or commas).                                                                                                                                                                                                                                                                                         |
| `--status <id>`        | <Badge size="sm" color="blue">string</Badge>    | <Icon icon="minus" size={14} />               | Only tasks in that workflow status (repeat or commas).                                                                                                                                                                                                                                                                                    |
| `--release-id <id>`    | <Badge size="sm" color="purple">integer</Badge> | <Icon icon="minus" size={14} />               | Only tasks in those releases (repeat or commas; combined with OR).                                                                                                                                                                                                                                                                        |
| `--untagged`           | <Badge size="sm" color="orange">flag</Badge>    | <Icon icon="minus" size={14} />               | Include tasks with no release (used together with **`--release-id`** as OR).                                                                                                                                                                                                                                                              |
| `--date-mode <mode>`   | <Badge size="sm" color="blue">string</Badge>    | <Icon icon="minus" size={14} />               | **`opened`**, **`closed`**, or **`any`**.                                                                                                                                                                                                                                                                                                 |
| `--from <yyyy-mm-dd>`  | <Badge size="sm" color="blue">string</Badge>    | <Icon icon="minus" size={14} />               | Start of date range (inclusive).                                                                                                                                                                                                                                                                                                          |
| `--to <yyyy-mm-dd>`    | <Badge size="sm" color="blue">string</Badge>    | <Icon icon="minus" size={14} />               | End of date range (inclusive).                                                                                                                                                                                                                                                                                                            |
| `--limit <n>`          | <Badge size="sm" color="purple">integer</Badge> | <Icon icon="minus" size={14} />               | Page size after server-side sort/filter (omit for one full response).                                                                                                                                                                                                                                                                     |
| `--offset <n>`         | <Badge size="sm" color="purple">integer</Badge> | <Icon icon="minus" size={14} />               | Skip this many tasks (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} />               | Print total matches 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: `taskId`, `boardId`, `boardSlug`, `listId`, `title`, `body`, `groupId`, `priorityId`, `status`, `order`, `color`, `emoji`, `createdAt`, `updatedAt`, `closedAt`, `createdByPrincipal`, `createdByLabel`, `releaseId`. See [Field projection](/task-manager/cli/cli-commands#field-projection). |

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

**CLI Examples**

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

<Expandable title="Example list response" defaultOpen={false}>
  ```json json theme={null}
  {"taskId":101,"boardId":1,"boardSlug":"sprint","listId":2,"groupId":1,"title":"Example","status":"open"}
  ```

  (Real tasks include more fields from the API; sample abbreviated.)
</Expandable>

***

### `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>`       | <Badge size="sm" color="purple">integer</Badge> | <Icon icon="check" color="green" size={14} /> | Global task id.                                                                                               |
| `--fields <keys>` | <Badge size="sm" color="blue">string</Badge>    | <Icon icon="minus" size={14} />               | Same allowlist as **`tasks list`** (see [Field projection](/task-manager/cli/cli-commands#field-projection)). |

**CLI examples**

```bash theme={null}
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                                            | Required                                      | Description                                                                                                                                  |
| -------------------------- | ----------------------------------------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `--board <id-or-slug>`     | <Badge size="sm" color="blue">string</Badge>    | <Icon icon="check" color="green" size={14} /> | Board id or slug.                                                                                                                            |
| `--list <id>`              | <Badge size="sm" color="purple">integer</Badge> | <Icon icon="check" color="green" size={14} /> | Column (list) id.                                                                                                                            |
| `--group <id>`             | <Badge size="sm" color="purple">integer</Badge> | <Icon icon="check" color="green" size={14} /> | Task group id.                                                                                                                               |
| `--title <text>`           | <Badge size="sm" color="blue">string</Badge>    | <Icon icon="minus" size={14} />               | Title (default **Untitled**).                                                                                                                |
| `--status <id>`            | <Badge size="sm" color="blue">string</Badge>    | <Icon icon="minus" size={14} />               | Workflow status (default **open**).                                                                                                          |
| `--priority <id>`          | <Badge size="sm" color="purple">integer</Badge> | <Icon icon="minus" size={14} />               | Priority row id (omit for built-in **none**).                                                                                                |
| `--release <name-or-none>` | <Badge size="sm" color="blue">string</Badge>    | <Icon icon="minus" size={14} />               | Release by exact name, or **`none`** for no release. Do not use together with **`--release-id`**.                                            |
| `--release-id <id>`        | <Badge size="sm" color="purple">integer</Badge> | <Icon icon="minus" size={14} />               | 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>`           | <Badge size="sm" color="blue">string</Badge>    | <Icon icon="minus" size={14} />               | Emoji before the title.                                                                                                                      |
| `--clear-emoji`            | <Badge size="sm" color="orange">flag</Badge>    | <Icon icon="minus" size={14} />               | Store no emoji.                                                                                                                              |
| `--body <text>`            | <Badge size="sm" color="blue">string</Badge>    | <Icon icon="minus" size={14} />               | Body (Markdown).                                                                                                                             |
| `--body-file <path>`       | <Badge size="sm" color="blue">string</Badge>    | <Icon icon="minus" size={14} />               | Read body from a text file.                                                                                                                  |
| `--body-stdin`             | <Badge size="sm" color="orange">flag</Badge>    | <Icon icon="minus" size={14} />               | Read body from the terminal until input ends.                                                                                                |

**CLI Examples**

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

<Prompt description="Add a task &#x22;Buy metro tickets&#x22; on board bucket-lists in list 2 and group 1." actions={["copy", "cursor"]}>
  Add a task "Buy metro tickets" on board bucket-lists in list 2 and group 1.
</Prompt>

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

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

***

### `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                                            | Required                                      | Description                                                  |
| -------------------------- | ----------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------ |
| `<task-id>`                | <Badge size="sm" color="purple">integer</Badge> | <Icon icon="check" color="green" size={14} /> | Task id.                                                     |
| `--title <text>`           | <Badge size="sm" color="blue">string</Badge>    | <Icon icon="minus" size={14} />               | New title.                                                   |
| `--body <text>`            | <Badge size="sm" color="blue">string</Badge>    | <Icon icon="minus" size={14} />               | Body (Markdown).                                             |
| `--body-file <path>`       | <Badge size="sm" color="blue">string</Badge>    | <Icon icon="minus" size={14} />               | Body from a text file.                                       |
| `--body-stdin`             | <Badge size="sm" color="orange">flag</Badge>    | <Icon icon="minus" size={14} />               | Body from the terminal until input ends.                     |
| `--status <id>`            | <Badge size="sm" color="blue">string</Badge>    | <Icon icon="minus" size={14} />               | Workflow status id.                                          |
| `--list <id>`              | <Badge size="sm" color="purple">integer</Badge> | <Icon icon="minus" size={14} />               | Move to this list id (column).                               |
| `--group <id>`             | <Badge size="sm" color="purple">integer</Badge> | <Icon icon="minus" size={14} />               | Task group id.                                               |
| `--priority <id>`          | <Badge size="sm" color="purple">integer</Badge> | <Icon icon="minus" size={14} />               | Priority row id (use built-in **none** id to reset).         |
| `--release <name-or-none>` | <Badge size="sm" color="blue">string</Badge>    | <Icon icon="minus" size={14} />               | Release by name, or **`none`**. Not with **`--release-id`**. |
| `--release-id <id>`        | <Badge size="sm" color="purple">integer</Badge> | <Icon icon="minus" size={14} />               | Release by id. Not with **`--release`**.                     |
| `--color <css>`            | <Badge size="sm" color="blue">string</Badge>    | <Icon icon="minus" size={14} />               | Card color (CSS).                                            |
| `--clear-color`            | <Badge size="sm" color="orange">flag</Badge>    | <Icon icon="minus" size={14} />               | Remove card color.                                           |
| `--emoji <text>`           | <Badge size="sm" color="blue">string</Badge>    | <Icon icon="minus" size={14} />               | Emoji before the title.                                      |
| `--clear-emoji`            | <Badge size="sm" color="orange">flag</Badge>    | <Icon icon="minus" size={14} />               | Remove emoji.                                                |

**CLI Examples**

```bash theme={null}
hirotm tasks update --title "Ship v1.1" 101
hirotm tasks update --list 3 --group 1 101
```

**AI Agent Examples**

<Prompt description="Set task 101 title to &#x22;Done when shipped&#x22;." actions={["copy", "cursor"]}>
  Set task 101 title to "Done when shipped".
</Prompt>

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

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

***

### `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                                            | Required                                      | Description                                                  |
| -------------------- | ----------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------ |
| `--to-list <id>`     | <Badge size="sm" color="purple">integer</Badge> | <Icon icon="check" color="green" size={14} /> | Destination column (list) id.                                |
| `<task-id>`          | <Badge size="sm" color="purple">integer</Badge> | <Icon icon="check" color="green" size={14} /> | Task id to move.                                             |
| `--to-status <id>`   | <Badge size="sm" color="blue">string</Badge>    | <Icon icon="minus" size={14} />               | Status in the destination (omit to keep the current status). |
| `--before-task <id>` | <Badge size="sm" color="purple">integer</Badge> | <Icon icon="minus" size={14} />               | Place before this task in the destination band.              |
| `--after-task <id>`  | <Badge size="sm" color="purple">integer</Badge> | <Icon icon="minus" size={14} />               | Place after this task in the destination band.               |
| `--first`            | <Badge size="sm" color="orange">flag</Badge>    | <Icon icon="minus" size={14} />               | First in the destination band.                               |
| `--last`             | <Badge size="sm" color="orange">flag</Badge>    | <Icon icon="minus" size={14} />               | Last in the destination band.                                |

**CLI Examples**

```bash theme={null}
hirotm tasks move --to-list 3 --first 101
hirotm tasks move --to-list 3 --after-task 99 101
```

**AI Agent Examples**

<Prompt description="Move task 101 to list 3 at the top." actions={["copy", "cursor"]}>
  Move task 101 to list 3 at the top.
</Prompt>

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

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

***

### `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                                            | Required                                      | Description                                                                                                |
| ------------- | ----------------------------------------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `<task-id>`   | <Badge size="sm" color="purple">integer</Badge> | <Icon icon="check" color="green" size={14} /> | Task 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 tasks delete 101
hirotm tasks delete 101 --dry-run
hirotm tasks delete 101 --yes
```

**AI Agent Examples**

<Prompt description="Move task 101 to Trash (non-interactive)." actions={["copy", "cursor"]}>
  hirotm tasks delete 101 --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-09T18:15:00.000Z",
      "trashed": {
        "type": "task",
        "taskId": 101,
        "trashed": true
      }
    }
    ```

    ```json error theme={null}
    {
      "error": "Task not found",
      "board": "sprint",
      "taskId": 101
    }
    ```
  </CodeGroup>
</Expandable>

***

### `tasks restore`

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

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

**CLI Examples**

```bash theme={null}
hirotm tasks restore 101
hirotm tasks restore 101 --yes
```

**AI Agent Examples**

<Prompt description="Restore task 101 from Trash (non-interactive)." actions={["copy", "cursor"]}>
  hirotm tasks restore 101 --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-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
      }
    }
    ```

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

***

### `tasks purge`

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

| Option        | Type                                            | Required                                      | Description                                                                                        |
| ------------- | ----------------------------------------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `<task-id>`   | <Badge size="sm" color="purple">integer</Badge> | <Icon icon="check" color="green" size={14} /> | Task id already in Trash.                                                                          |
| `--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 tasks purge 101
hirotm tasks purge 101 --dry-run
hirotm tasks purge 101 --yes
```

**AI Agent Examples**

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

<Expandable title="Example responses" defaultOpen={false}>
  <CodeGroup>
    ```json json theme={null}
    {
      "ok": true,
      "purged": {
        "type": "task",
        "taskId": 101
      }
    }
    ```

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

***

## Learn more

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