# uip ah categories, tags, collaborators, roles, users

> Syntax and options for the Automation Hub category taxonomy, free-text tags, per-automation collaborators, the assignable role catalogue, and user accounts.

**Categories** are a hierarchical taxonomy automations are placed in; **tags** are free-text labels. **Collaborators** are the people working on one automation, each holding one or more **roles** — Automation Hub's assignable-role catalogue is also how `uip ah users create` grants tenant-wide access. See [`uip ah`](./uip-ah.md) for shared concepts (projection/`--all-fields`, paged vs. unpaged lists) that apply to every verb here.

## uip ah categories

Read the category hierarchy and place automations in it.

### Synopsis

```text
uip ah categories get [--all-fields]
uip ah categories update --file <json-file> [-y, --yes]
uip ah categories set <automation-id> --category-id <id>
```

### uip ah categories get

Get the category hierarchy as one tree, with its level names. `get`, not `list`: the endpoint returns one nested document, not a paged collection — there's no `--limit`/`--offset`.

#### Options

| Long | Description |
|---|---|
| `--all-fields` | Return the raw payload instead of `Levels`/`Categories`. |

#### Example

```bash
uip ah categories get
```

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

```json
{
  "Code": "AhCategoriesGet",
  "Data": { "Levels": [{ "Id": 1, "Name": "Business Unit" }], "Categories": [{ "Id": 4, "Name": "Finance" }] }
}
```

### uip ah categories update

Replace the whole category tree from a file. Automation Hub has no per-category create/delete — the tree is synced as one document.

#### Options

| Long | Value | Required | Description |
|---|---|---|---|
| `--file <json-file>` | path | **yes** | JSON with the full category tree to sync, in the shape `categories get` returns. |
| `-y, --yes` | flag | **yes** | Confirm this replaces the entire tenant category tree. Required — the CLI never prompts. |

An empty or clearly-malformed file is rejected client-side before the request is sent.

#### Example

```bash
uip ah categories update --file ./categories.json --yes
```

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

```json
{ "Code": "AhCategoriesUpdate", "Data": { "Status": "Synced" } }
```

### uip ah categories set

Assign one automation to a category.

#### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<automation-id>` | yes | Automation id. |

#### Options

| Long | Value | Required | Description |
|---|---|---|---|
| `--category-id <id>` | integer | **yes** | Category id to assign. |

#### Example

```bash
uip ah categories set 20 --category-id 4
```

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

```json
{ "Code": "AhCategoriesSet", "Data": { "AutomationId": 20, "CategoryId": 4 } }
```

## uip ah tags

Set the tags on an automation.

### uip ah tags set

Replace an automation's tags with the given set — this replaces the whole tag list rather than merging (matching `uip config set`'s replace semantics).

#### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<automation-id>` | yes | Automation id. |

#### Options

| Long | Value | Required | Description |
|---|---|---|---|
| `--tags <tag...>` | repeatable | **yes** | The complete tag set for this automation. |

#### Example

```bash
uip ah tags set 20 --tags finance "quick win"
```

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

```json
{ "Code": "AhTagsSet", "Data": { "AutomationId": 20, "Tags": ["finance", "quick win"] } }
```

## uip ah collaborators

Manage who collaborates on an automation. Its own resource group rather than a verb on `automations`, so the standard CRUD verbs stay available for it.

### Synopsis

```text
uip ah collaborators list --automation-id <id> [--limit <n>] [--offset <n>] [--all-fields]
uip ah collaborators create <automation-id> --user-id <id...> --role-id <id...>
uip ah collaborators delete <automation-id> --user-id <id...> --role-id <id...> [-y, --yes]
```

### uip ah collaborators list

#### Options

| Long | Value | Required | Description |
|---|---|---|---|
| `--automation-id <id>` | integer | **yes** | Automation to read (a query parameter on this endpoint, not a positional). |
| `--limit <n>` / `--offset <n>` | integer | no | Paging, applied client-side (unpaged endpoint). |
| `--all-fields` | flag | no | Return the raw payload. |

#### Example

```bash
uip ah collaborators list --automation-id 20
```

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

```json
{
  "Code": "AhCollaboratorsList",
  "Data": [
    { "Id": 1, "Email": "jane@acme.com", "FirstName": "Jane", "LastName": "Doe", "JobTitle": "Analyst", "Department": "Finance", "BusinessUnit": "EMEA", "IsActive": 1 }
  ]
}
```

### uip ah collaborators create

Add collaborators to an automation.

#### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<automation-id>` | yes | Automation id. |

#### Options

| Long | Value | Required | Description |
|---|---|---|---|
| `--user-id <id...>` | repeatable | **yes** | User ids to add. |
| `--role-id <id...>` | repeatable | **yes** | Role ids to grant every added user (applied to all of them — a per-user role split needs one call per user). Only active roles of type `process` are accepted; the endpoint rejects any other kind. |

At least one `--role-id` is required — the endpoint rejects a collaborator entry with no role.

#### Example

```bash
uip ah collaborators create 20 --user-id 3 --role-id 3
```

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

```json
{ "Code": "AhCollaboratorsCreate", "Data": { "AutomationId": 20, "UserIds": [3] } }
```

### uip ah collaborators delete

Remove collaborator roles from users on an automation. The endpoint deletes role assignments rather than the collaborator record, so `--role-id` is required — strip every role a user holds and they stop being a collaborator.

#### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<automation-id>` | yes | Automation id. |

#### Options

| Long | Value | Required | Description |
|---|---|---|---|
| `--user-id <id...>` | repeatable | **yes** | User ids to remove roles from. |
| `--role-id <id...>` | repeatable | **yes** | Role ids to remove from each user. |
| `-y, --yes` | flag | **yes** | Confirm this irreversible operation. Required — the CLI never prompts. |

#### Example

```bash
uip ah collaborators delete 20 --user-id 3 --role-id 3 --yes
```

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

```json
{ "Code": "AhCollaboratorsDelete", "Data": { "AutomationId": 20, "UserIds": [3], "RoleIds": [3] } }
```

## uip ah roles

Discover the Automation Hub roles that can be assigned. Read-only.

### uip ah roles list

#### Options

| Long | Description |
|---|---|
| `--limit <n>` / `--offset <n>` | Paging, applied client-side (unpaged endpoint). |
| `--all-fields` | Return the raw payload. |

#### Example

```bash
uip ah roles list
```

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

```json
{
  "Code": "AhRolesList",
  "Data": [
    { "Id": 2, "Name": "System Admin", "Slug": "ah-system-admin", "Type": "service", "Description": "...", "IsActive": 1, "IsDefault": 0 }
  ]
}
```

`Slug` is the value `uip ah users create --role` takes; `Id`/`Type` are what `collaborators create --role-id` filters on (only `Type: "process"` roles are accepted there).

## uip ah users

Manage Automation Hub users and their roles.

### Synopsis

```text
uip ah users list [--search <text>] [--sort-by <field>] [--sort-order asc|desc] [--department <name>] [--business-unit <name>] [--location <name>] [--job-title <title>] [--invite-status <status>] [--role <slug>] [--limit <n>] [--offset <n>] [--all-fields]
uip ah users create --email <email> [write options...] --role-id <id...>
uip ah users update --email <email> [write options...]
```

### uip ah users list

#### Options

| Long | Value | Description |
|---|---|---|
| `--search <text>` | string | Free-text search. |
| `--sort-by <field>` | string | Field to sort on, e.g. `user_email`. |
| `--sort-order <direction>` | `asc`\|`desc` | Sort direction. |
| `--department <name>` / `--business-unit <name>` / `--location <name>` / `--job-title <title>` | string | Scope filters. |
| `--invite-status <status>` | string | Only this invite status. |
| `--role <slug>` | string | Only users holding this role slug. |
| `--limit <n>` / `--offset <n>` | integer | Paging. Default `--limit 20`. |
| `--all-fields` | flag | Return the raw payload. |

#### Example

```bash
uip ah users list --department Finance --limit 20
```

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

```json
{
  "Code": "AhUsersList",
  "Data": [
    { "Id": 3, "Email": "jane@acme.com", "FirstName": "Jane", "LastName": "Doe", "JobTitle": "Analyst", "Department": "Finance", "BusinessUnit": "EMEA", "Location": "Boston", "IsAdmin": 0, "IsActive": 1, "InviteStatus": 2, "AutomationCount": 3 }
  ],
  "Pagination": { "Returned": 1, "Limit": 20, "Offset": 0 }
}
```

### uip ah users create

Add an existing Automation Cloud user to Automation Hub. This imports a user who is already in the organization — it cannot invite a new one, and fails with an explicit instructional error if the address is unknown to Automation Cloud.

#### Options

| Long | Value | Required | Description |
|---|---|---|---|
| `--email <email>` | email | **yes** | User email address. |
| `--first-name <name>` / `--last-name <name>` | string | conditionally | Required by the service on write (see below). |
| `--job-title <title>` / `--department <name>` / `--business-unit <name>` / `--location <name>` | string | conditionally | Required by the service on write. |
| `--invite-status <status>` | integer | no | Numeric Automation Hub invite-status code. Default `2` on create. |
| `--active` | flag | no | Mark the user active. Default on create. Conflicts with `--inactive`. |
| `--inactive` | flag | no | Mark the user inactive. Conflicts with `--active`. |
| `--role-id <id...>` | repeatable | no | Role ids to assign (`uip ah roles list` for the ids). |

Automation Hub requires nine fields to carry a value on every write (`email`, `first-name`, `last-name`, `business-unit`, `department`, `location`, `job-title`, `invite-status`, `active`/`inactive`) — on `create`, none has a stored fallback, so any omitted field fails client-side naming exactly which flags to pass.

#### Example

```bash
uip ah users create --email jane@acme.com --first-name Jane --last-name Doe \
  --job-title Analyst --department Finance --business-unit EMEA --location Boston --role-id 3
```

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

```json
{ "Code": "AhUsersCreate", "Data": { "Email": "jane@acme.com", "Status": "Created" } }
```

### uip ah users update

Update a user, found by `--email`. Automation Hub replaces the whole user record on write, so fields you don't pass are carried over from the stored record — except that the service still rejects the write if any of the nine required fields is empty on both the flag and the stored record.

#### Options

Same flags as `create`, but only `--email` is required — the rest fill gaps from the existing record.

#### Example

```bash
uip ah users update --email jane@acme.com --job-title 'Senior Analyst'
```

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

```json
{ "Code": "AhUsersUpdate", "Data": { "Email": "jane@acme.com", "Status": "Updated" } }
```

## Related

- [`uip ah`](./uip-ah.md) — overview, concepts, `audit-logs`, `auth-info`.
- [Automations, idea-flows, business-cases, phases, questionnaires, pipelines](./uip-ah-automations.md)
- [Applications, components, documents, media, store-listings, store-reviews](./uip-ah-catalog.md)

## See also

- [Tools (plugins)](./concepts-tools.md)
- [Global options](./global-options.md)
- [Exit codes](./exit-codes.md)