> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oqoqo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# oqoqo tags

> List, add, remove, rename, and delete tags on tasks, files, machines, tools, treatments, and experiments, and filter lists by tag.

A [tag](https://docs.oqoqo.ai/experiments/tags.md) is a project label with a stable `tag_` ID that helps you find records again. It never changes what a record does or how a run uses it.

## Refer to tags and records

Name a tag by its `tag_` ID or by its name in any case (`Flaky` and `flaky` are the same tag). Quote a name with spaces. Name a record by its public ID:

| Prefix | Record |
| - | - |
| `tsk_` | Task. Use the task ID, not a task version ID. |
| `fld_` | File |
| `env_` | Machine |
| `skl_`, `mcp_`, `cli_`, `sdk_` | Skill, MCP server, CLI, or SDK |
| `trt_` | Treatment (toolset) |
| `exp_` | Experiment |

Tags go on the record, not a version, so new versions keep them. Agents, runs, frictions, and projects have no tags.

## oqoqo tags list

List the project's tags, with each one's `tag_` ID and how many records of each kind have it.

```bash theme={null}
oqoqo tags list [flags]
```

**Plugin (MCP) tool:** [`list_tags`](https://docs.oqoqo.ai/mcp-server/tags-and-data#list_tags)

**Flags**

| Flag | Type | Default | Description |
| - | - | - | - |
| `--query` | string | | Only tags whose name contains this text, up to 40 characters. |

Also takes the [global flags](https://docs.oqoqo.ai/cli/overview.md#global-flags).

**Examples**

List the project's tags:

```bash theme={null}
oqoqo tags list
```

**Result fields**

| Field | Meaning |
| - | - |
| `id`, `name` | The tag's `tag_` ID and name |
| `usage` | How many records have the tag, in total and by kind |
| `createdAt`, `updatedAt` | When the tag was created and last changed. Rename and delete check `updatedAt`. |

## oqoqo tags add

Add tags to up to 100 records at once. A new name creates the tag.

```bash theme={null}
oqoqo tags add <tag>... --to <record-ids> [flags]
```

**Plugin (MCP) tool:** [`update_tags`](https://docs.oqoqo.ai/mcp-server/tags-and-data#update_tags)

**Arguments**

| Argument | Description |
| - | - |
| `<tag>...` | Required. Up to 20 tag names or `tag_` IDs. |

**Flags**

| Flag | Type | Default | Description |
| - | - | - | - |
| `--to` | string | | Required. Up to 100 comma-separated [record IDs](#refer-to-tags-and-records). |

Also takes the [global flags](https://docs.oqoqo.ai/cli/overview.md#global-flags).

**Examples**

Tag a task and an experiment:

```bash theme={null}
oqoqo tags add needs-review regression --to tsk_3a91c7e2,exp_8f2c41d0
```

Add a tag with a space in its name:

```bash theme={null}
oqoqo tags add "release 11" --to trt_51be0c9a
```

**Result fields**

| Field | Meaning |
| - | - |
| `records` | Each record's `id`, `kind`, and all its `tags` after the change |
| `createdTags` | The tags this change created, each with `id` and `name` |

**Notes**

You can run the command again safely: a record that already has a tag keeps it. A change that goes over a [limit](#names-and-limits) changes nothing and fails with `tag_limit_exceeded`, which names the limit.

## oqoqo tags remove

Remove tags from up to 100 records at once. The tags stay in the project.

```bash theme={null}
oqoqo tags remove <tag>... --from <record-ids> [flags]
```

**Plugin (MCP) tool:** [`update_tags`](https://docs.oqoqo.ai/mcp-server/tags-and-data#update_tags)

**Arguments**

| Argument | Description |
| - | - |
| `<tag>...` | Required. Up to 20 tag names or `tag_` IDs. |

**Flags**

| Flag | Type | Default | Description |
| - | - | - | - |
| `--from` | string | | Required. Up to 100 comma-separated [record IDs](#refer-to-tags-and-records). |

Also takes the [global flags](https://docs.oqoqo.ai/cli/overview.md#global-flags).

**Examples**

Remove a tag from a task:

```bash theme={null}
oqoqo tags remove regression --from tsk_3a91c7e2
```

**Result fields**

`records` and `createdTags`, as in [`oqoqo tags add`](#oqoqo-tags-add): each record's `id`, `kind`, and `tags` after the change.

**Notes**

You can run the command again safely. To remove a tag from every record and from the project, use [`oqoqo tags delete`](#oqoqo-tags-delete).

## oqoqo tags rename

Rename a tag everywhere. Its `tag_` ID stays, so every record keeps it.

```bash theme={null}
oqoqo tags rename <tag> <name> [flags]
```

**Plugin (MCP) tool:** [`rename_tag`](https://docs.oqoqo.ai/mcp-server/tags-and-data#rename_tag)

**Arguments**

| Argument | Description |
| - | - |
| `<tag>` | Required. The tag's `tag_` ID or current name. |
| `<name>` | Required. The new name. |

**Flags**

| Flag | Type | Default | Description |
| - | - | - | - |
| `--expected-updated-at` | ISO 8601 date-time | The tag's current `updatedAt` | The `updatedAt` from `oqoqo tags list`. Refused if the tag changed since. |

Also takes the [global flags](https://docs.oqoqo.ai/cli/overview.md#global-flags).

**Examples**

Rename a tag:

```bash theme={null}
oqoqo tags rename needs-review "needs review"
```

**Result fields**

The result has the renamed `tag`, with its `id`, `name`, `usage`, `createdAt`, and `updatedAt`.

**Notes**

A name that another tag already has, in any case, fails with `tag_name_taken`. A tag that changed since you read it fails with `tag_changed`, so run the command again.

## oqoqo tags delete

Delete a tag from the project and every record. The records stay.

```bash theme={null}
oqoqo tags delete <tag> [flags]
```

**Plugin (MCP) tool:** [`delete_tag`](https://docs.oqoqo.ai/mcp-server/tags-and-data#delete_tag)

> [!WARNING]
>
> This can't be undone. In a terminal, the CLI says how many records have the tag and asks you to confirm. With `--output json`, or without a terminal, pass `--yes`.

**Arguments**

| Argument | Description |
| - | - |
| `<tag>` | Required. The tag's `tag_` ID or name. |

**Flags**

| Flag | Type | Default | Description |
| - | - | - | - |
| `--expected-updated-at` | ISO 8601 date-time | The tag's current `updatedAt` | The `updatedAt` from `oqoqo tags list`. Refused if the tag changed since. |
| `--yes` | boolean | `false` | Skip interactive confirmation. Required with `--output json` or outside a terminal. |

Also takes the [global flags](https://docs.oqoqo.ai/cli/overview.md#global-flags).

**Examples**

Delete a tag in a script:

```bash theme={null}
oqoqo tags delete regression --yes --output json
```

**Result fields**

| Field | Meaning |
| - | - |
| `tag` | The deleted tag's `id` and `name` |
| `removedFrom` | How many records had the tag |

**Notes**

A tag the project doesn't have fails with `tag_not_found`. When you delete a tagged task, tool, treatment, or experiment, its tags stay in the project.

## Filter lists by tag

[`oqoqo catalog list`](https://docs.oqoqo.ai/cli/catalog#oqoqo-catalog-list) and [`oqoqo experiments list`](https://docs.oqoqo.ai/cli/experiments#oqoqo-experiments-list) take two tag filters.

| Flag | Type | Description |
| - | - | - |
| `--tag` | string | Comma-separated tag names or `tag_` IDs. Records with any of them. |
| `--untagged` | boolean | Records with no tags. With `--tag`, records with any of those tags or none. |

A tag the project doesn't have fails with `tag_not_found`, not an empty list, and `details.tags` names it. Each returned record lists its tags.

```bash theme={null}
oqoqo catalog list --tag needs-review
oqoqo experiments list --tag release-11,release-12
oqoqo catalog list --untagged
```

## Names and limits

| Rule | Limit |
| - | - |
| Name length | 1 to 40 characters |
| Characters | Any, except a comma and control characters. A name cannot look like a tag ID (`tag_…`). |
| Spaces | Spaces at the start and end are removed. Two or more spaces become one. |
| Tags on one record | 20 |
| Tags in one project | 500 |
| Records in one change | 100 |
| Tags named in one change or one filter | 20 |

## Related

> [card] [Tags](https://docs.oqoqo.ai/experiments/tags.md)
>
> Add and filter tags in the dashboard.

> [card] [oqoqo catalog, resources, and uploads](https://docs.oqoqo.ai/cli/catalog.md)
>
> Find tagged tasks, tools, and treatments.

> [card] [oqoqo experiments](https://docs.oqoqo.ai/cli/experiments.md)
>
> Find tagged experiments.

> [card] [IDs and limits](https://docs.oqoqo.ai/reference/ids-and-limits.md)
>
> Every ID prefix and product limit.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.