# uip tasks

> Commands for managing Action Center tasks, catalogs, comments, labels, metadata, and task data using the `uip tasks` tool.

`uip tasks` manages **Action Center** tasks — the human-in-the-loop work items (form fills, approvals, document validation/classification, data labeling) that RPA processes and agents create for a person to complete. The tool lets you list and inspect tasks, assign or reassign them, complete them with an action and data payload, and manage the auxiliary resources attached to a task: catalogs (grouping/retention config), comments, labels (tags), metadata (title/priority/catalog link), and the task's own form/business data. `tasks` is the command prefix; the underlying package is `@uipath/tasks-tool`.

## Concepts

- **Folder scoping** — every verb that operates on a specific task or catalog accepts `--folder-id <id>`, `--folder-path <path>`, or `--folder-key <key>` (mutually exclusive; enforced at parse time via Commander conflicts). When none is passed on an interactive terminal, the CLI shows a folder picker; in a non-interactive run (CI, coding agents) it fails fast asking for one. `uip tasks list` and `uip tasks get` are the two exceptions — a folder is optional there and simply narrows the results/lookup when given.
- **Task type** — several verbs (`get --task-type`, `complete --type`) take one of `FormTask`, `ExternalTask`, `AppTask`, `DocumentValidationTask`, `DocumentClassificationTask`, `DataLabelingTask`, `QuickFormTask`. An unrecognized value fails client-side with the full list named in the error.
- **Pagination** — list-style verbs (`list`, `catalogs list`, `comments list`, `users`) page internally with a 100-item page size and follow `nextCursor` until exhausted or `--limit` is reached, returning one flat array either way — there's no cursor flag to manage yourself.
- **Catalogs are optional grouping/retention config for tasks** — `metadata --catalog-id` links a task to one; `catalogs create`/`update`'s retention fields (`--retention-action`, `--retention-period`, `--retention-bucket-id`) control what happens to catalog data over time. `--encrypted` on `catalogs create` is immutable — there's no way to change it via `catalogs update`.

## Synopsis

```text
uip tasks list [--folder-id <id> | --folder-path <path> | --folder-key <key>] [--as-admin] [-l, --limit <n>]
uip tasks get <id> [--task-type <type>] [--folder-id <id> | --folder-path <path> | --folder-key <key>]
uip tasks assign <task-id> (--user-id <id> | --user <email>)
uip tasks reassign <task-id> (--user-id <id> | --user <email>)
uip tasks unassign <task-id>
uip tasks complete <task-id> --type <type> [--data <json>] [--action <action>] [--folder-id <id> | --folder-path <path> | --folder-key <key>]
uip tasks users [folder-id] [--folder-path <path> | --folder-key <key>] [-l, --limit <n>]

uip tasks catalogs list [--folder-id <id> | --folder-path <path> | --folder-key <key>] [-l, --limit <n>]
uip tasks catalogs get <id> [--folder-id <id> | --folder-path <path> | --folder-key <key>]
uip tasks catalogs create --name <name> [--description <text>] [--encrypted] [--retention-action <action>] [--retention-period <days>] [--retention-bucket-id <id>] [--folder-id <id> | --folder-path <path> | --folder-key <key>]
uip tasks catalogs update <id> [--name <name>] [--description <text>] [--retention-action <action>] [--retention-period <days>] [--retention-bucket-id <id>] [--folder-id <id> | --folder-path <path> | --folder-key <key>]

uip tasks comments list <task-id> [-l, --limit <n>] [folder options]
uip tasks comments add <task-id> --text <text> [folder options]

uip tasks labels <task-id> --labels <json> [folder options]
uip tasks metadata <task-id> [--title <text>] [--priority <level>] [--catalog-id <id> | --unset-catalog] [--note <text>] [folder options]

uip tasks data get <task-id> [folder options]
uip tasks data save <task-id> --data <json> [folder options]
```

## uip tasks list

List tasks across folders (or one folder, when scoped).

### Options

| Long | Value | Description |
|---|---|---|
| `--folder-id <id>` | integer | Filter by folder ID. |
| `--folder-path <path>` | string | Filter by folder path (alternative to `--folder-id`). |
| `--folder-key <key>` | GUID | Filter by folder key (alternative to `--folder-id`). |
| `--as-admin` | flag | List tasks as admin (broader visibility than your own assigned/available tasks). |
| `-l, --limit <number>` | integer | Maximum items to return. Fetches everything (paging internally) when omitted. |

### Example

```bash
uip tasks list --folder-path "Shared/Finance" --limit 20
```

### Data shape (--output json)

```json
{ "Code": "TaskList", "Data": [ { "id": 1, "title": "Approve invoice", "type": "FormTask", "status": "Pending" } ] }
```

## uip tasks get

Get details of a task by ID.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<id>` | yes | Task ID. Use `tasks list` to find one. |

### Options

| Long | Value | Description |
|---|---|---|
| `--task-type <type>` | one of the 7 task types | Task type. **Requires a folder option when passed** — fails fast otherwise. |
| `--folder-id <id>` / `--folder-path <path>` / `--folder-key <key>` | | Folder scope. Required only when `--task-type` is set. |

### Example

```bash
uip tasks get 123 --task-type FormTask --folder-id 42
```

### Data shape (--output json)

```json
{ "Code": "TaskDetails", "Data": { "id": 123, "title": "Approve invoice", "type": "FormTask", "status": "Pending" } }
```

## uip tasks assign / reassign

Assign a task to a user, or reassign it to a different one — identical option shape, different `Code` on success.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<task-id>` | yes | Task ID. |

### Options

| Long | Value | Required | Description |
|---|---|---|---|
| `--user-id <id>` | integer | one of these two | Assignee's numeric user ID. |
| `--user <email>` | string | one of these two | Assignee's username or email (alternative to `--user-id`). |

Passing neither fails with an explicit "missing assignee" error.

### Example

```bash
uip tasks assign 123 --user alice@company.com
uip tasks reassign 123 --user-id 7
```

### Data shape (--output json)

```json
{ "Code": "TaskAssigned", "Data": { "id": 123, "assignedTo": "alice@company.com" } }
```

`Code` is `TaskReassigned` for `reassign`.

## uip tasks unassign

Remove the assignee from a task. No options beyond the task ID.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<task-id>` | yes | Task ID. |

### Example

```bash
uip tasks unassign 123
```

### Data shape (--output json)

```json
{ "Code": "TaskUnassigned", "Data": { "id": 123 } }
```

## uip tasks complete

Complete a task with an action and optional data payload.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<task-id>` | yes | Task ID. |

### Options

| Long | Value | Required | Description |
|---|---|---|---|
| `--type <type>` | one of the 7 task types | **yes** | Task type — validated client-side against the enum. |
| `--data <json>` | JSON | no | Task data payload as a JSON string. |
| `--action <action>` | string | conditionally | Action name. Required in practice for `FormTask` and `AppTask` (not enforced client-side — the platform rejects a missing action for those types). |
| Folder options | | no | A folder is resolved (interactively if omitted, on a TTY) before completing. |

### Example

```bash
uip tasks complete 123 --type FormTask --action Approve --data '{"comment":"Looks good"}'
```

### Data shape (--output json)

```json
{ "Code": "TaskCompleted", "Data": { "id": 123, "status": "Completed" } }
```

## uip tasks users

List users with task permissions in a folder — the source for `--user-id`/`--user` values on `assign`/`reassign`.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `[folder-id]` | no | Folder ID as a positional argument. Mutually exclusive with `--folder-path`/`--folder-key` — passing both fails explicitly. |

### Options

| Long | Value | Description |
|---|---|---|
| `--folder-path <path>` | string | Folder path (alternative to the positional argument). |
| `--folder-key <key>` | GUID | Folder key (alternative to the positional argument). |
| `-l, --limit <number>` | integer | Maximum items to return. |

### Example

```bash
uip tasks users 42
uip tasks users --folder-path "Shared/Finance" --limit 10
```

### Data shape (--output json)

```json
{
  "Code": "TaskUserList",
  "Data": [
    { "id": 1, "name": "Alice", "surname": "Smith", "userName": "alice", "emailAddress": "alice@company.com", "displayName": "Alice Smith" }
  ]
}
```

## uip tasks catalogs

Manage task catalogs — named groupings of tasks with optional encryption and retention policy.

### uip tasks catalogs list

#### Options

| Long | Value | Description |
|---|---|---|
| Folder options | | Folder to list catalogs in (a folder is resolved if omitted, per [Concepts](#concepts)). |
| `-l, --limit <number>` | integer | Maximum items to return. |

#### Example

```bash
uip tasks catalogs list --folder-id 42
```

#### Data shape (--output json)

```json
{ "Code": "TaskCatalogList", "Data": [ { "id": 5, "name": "Invoices", "encrypted": false } ] }
```

### uip tasks catalogs get

#### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<id>` | yes | Task catalog ID. |

#### Example

```bash
uip tasks catalogs get 5 --folder-id 42
```

#### Data shape (--output json)

```json
{ "Code": "TaskCatalogDetails", "Data": { "id": 5, "name": "Invoices", "encrypted": false } }
```

### uip tasks catalogs create

#### Options

| Long | Value | Required | Description |
|---|---|---|---|
| `--name <name>` | string | **yes** | Catalog name. |
| `--description <text>` | string | no | Catalog description. |
| `--encrypted` | flag | no | Encrypt task data in this catalog. **Immutable** — cannot be changed by `catalogs update` later. |
| `--retention-action <action>` | `Delete` \| `Archive` | no | What happens at the retention limit. Any other value fails client-side. |
| `--retention-period <days>` | integer | no | Retention period in days. |
| `--retention-bucket-id <id>` | integer | no | Storage bucket ID, used when `--retention-action Archive`. |

#### Example

```bash
uip tasks catalogs create --name Invoices --retention-action Archive --retention-period 90 --retention-bucket-id 3 --folder-id 42
```

#### Data shape (--output json)

```json
{ "Code": "TaskCatalogCreated", "Data": { "id": 5, "name": "Invoices" } }
```

### uip tasks catalogs update

Merges — only the flags you pass change. At least one of `--name`/`--description`/`--retention-action`/`--retention-period`/`--retention-bucket-id` is required; calling with none fails before any file/network access. `--encrypted` cannot be changed here.

#### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<id>` | yes | Task catalog ID. |

#### Options

Same set as `create` minus `--encrypted`.

#### Example

```bash
uip tasks catalogs update 5 --name "Invoices v2" --folder-id 42
```

#### Data shape (--output json)

```json
{ "Code": "TaskCatalogUpdated", "Data": { "id": 5, "name": "Invoices v2" } }
```

## uip tasks comments

### uip tasks comments list

#### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<task-id>` | yes | Task ID. |

#### Options

| Long | Value | Description |
|---|---|---|
| `-l, --limit <number>` | integer | Maximum items to return. |
| Folder options | | Folder the task lives in. |

#### Example

```bash
uip tasks comments list 123 --folder-id 42
```

#### Data shape (--output json)

```json
{ "Code": "TaskCommentList", "Data": [ { "id": 1, "text": "Looks good", "createdBy": "alice" } ] }
```

### uip tasks comments add

#### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<task-id>` | yes | Task ID. |

#### Options

| Long | Value | Required | Description |
|---|---|---|---|
| `--text <text>` | string | **yes** | Comment text. Empty string is rejected. |
| Folder options | | no | Folder the task lives in. |

#### Example

```bash
uip tasks comments add 123 --text "Escalating to finance" --folder-id 42
```

#### Data shape (--output json)

```json
{ "Code": "TaskCommentCreated", "Data": { "id": 2, "text": "Escalating to finance" } }
```

## uip tasks labels

Set or clear the labels (tags) on a task in one call — this is a full replace, not a merge; pass every label you want to keep.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<task-id>` | yes | Task ID. |

### Options

| Long | Value | Required | Description |
|---|---|---|---|
| `--labels <json>` | JSON array | **yes** | Labels to set, e.g. `[{"name":"region","displayName":"Region","displayValue":"EMEA"}]`. Pass `[]` to clear all labels. Must be a JSON array — a non-array value fails client-side. |
| Folder options | | no | Folder the task lives in. |

### Example

```bash
uip tasks labels 123 --labels '[{"name":"region","displayName":"Region","displayValue":"EMEA"}]' --folder-id 42
```

### Data shape (--output json)

```json
{ "Code": "TaskLabelsSaved", "Data": { "taskId": 123, "labels": [{ "name": "region", "displayName": "Region", "displayValue": "EMEA" }] } }
```

## uip tasks metadata

Edit a task's title, priority, catalog link, and record a note with the edit. Merges — only the flags you pass change; at least one is required.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<task-id>` | yes | Task ID. |

### Options

| Long | Value | Description |
|---|---|---|
| `--title <title>` | string | New title. |
| `--priority <priority>` | `Low` \| `Medium` \| `High` \| `Critical` | New priority. An out-of-set value fails client-side, naming the valid set. |
| `--catalog-id <id>` | integer | Associate a task catalog. Mutually exclusive with `--unset-catalog`. |
| `--unset-catalog` | flag | Remove the task's catalog association. Mutually exclusive with `--catalog-id`. |
| `--note <text>` | string | Comment recorded alongside the edit. |

### Example

```bash
uip tasks metadata 123 --priority High --note "Escalated per manager request" --folder-id 42
```

### Data shape (--output json)

```json
{ "Code": "TaskMetadataEdited", "Data": { "taskId": 123 } }
```

## uip tasks data

Read or write a task's underlying form/business data object.

### uip tasks data get

#### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<task-id>` | yes | Task ID. |

#### Example

```bash
uip tasks data get 123 --folder-id 42
```

#### Data shape (--output json)

```json
{ "Code": "TaskData", "Data": { "invoiceNumber": "INV-001", "amount": 250.0 } }
```

### uip tasks data save

#### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<task-id>` | yes | Task ID. |

#### Options

| Long | Value | Required | Description |
|---|---|---|---|
| `--data <json>` | JSON object | **yes** | Task data to save. Must be a JSON object (not an array or scalar) — anything else fails client-side. |

#### Example

```bash
uip tasks data save 123 --data '{"invoiceNumber":"INV-001","amount":250.0}' --folder-id 42
```

#### Data shape (--output json)

```json
{ "Code": "TaskDataSaved", "Data": { "taskId": 123 } }
```

## See also

- [Concepts: how UiPath CLI is organized](./concepts-cli-architecture.md) — where tools fit in the host + tool model.
- [Sessions](./concepts-sessions.md) — how tenant context is resolved.
- [`uip or folders`](./uip-or-folders.md) — find folder IDs/paths/keys for the folder-scoping options on this page.
- [`uip login`](./uip-login.md) — session used for all Action Center calls.
- [Global options](./global-options.md)
- [Exit codes](./exit-codes.md)