> For the complete documentation index, see [llms.txt](https://developer.celigo.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.celigo.com/cli/commands/tags.md).

# tags

Short, shareable labels that mark resources (flows, errors, integrations) so teams can filter and triage them consistently.

**REST API**: [Tags](https://developer.celigo.com/api/api-reference/tags). Tag references appear on other resources (notifications, flow errors) via the `tagIds` field.

**OpenAPI spec**: `dist/tag.yml` in `@celigo/api-specs` — see [OpenAPI specs](https://developer.celigo.com/api/using-the-api/openapi-specs)

Supports all [global flags](/cli/getting-started/global-flags.md).

## Subcommands

| Command                         | Purpose                                                                  |
| ------------------------------- | ------------------------------------------------------------------------ |
| [`list`](#celigo-tags-list)     | List every tag on the account.                                           |
| [`get`](#celigo-tags-get)       | Fetch one tag by id.                                                     |
| [`create`](#celigo-tags-create) | Create a new tag from a JSON body (`--file <path>` or stdin).            |
| [`update`](#celigo-tags-update) | Full-replace PUT from a JSON body (`--file <path>` or stdin).            |
| [`set`](#celigo-tags-set)       | Patch fields with `key=value` assignments. Supports `key=file://<path>`. |
| [`delete`](#celigo-tags-delete) | Delete a tag.                                                            |

## celigo tags list

List every tag. Columns: `_id`, `tag`, `tagId`, `lastModified`.

In celigo-cli 2026.8.1 through 2026.8.8 the default `list` failed with `422 Unprocessable Entity` because the endpoint rejects the `include` projection, and only `--fields all` worked; since 2026.9.1 the default form works again (rows are trimmed client-side to the same columns).

```bash
celigo tags list
```

**Corresponds to**: [`GET /v1/tags`](https://developer.celigo.com/api/api-reference/tags#get-v1-tags)

## celigo tags get

Fetch one tag by id.

```bash
celigo tags get <id>
```

**Corresponds to**: [`GET /v1/tags/{_id}`](https://developer.celigo.com/api/api-reference/tags#get-v1-tags-_id)

## celigo tags create

Create a tag from a JSON body. Read the body from a file with `-f, --file` (recommended), or pipe it on stdin (`--file -` also means stdin). The minimal shape is `{"tag":"<label>"}`.

| Flag                | Description                                                                                                  |
| ------------------- | ------------------------------------------------------------------------------------------------------------ |
| `-f, --file <path>` | Read the JSON body from a file instead of stdin (`--file -` also means stdin). Added in celigo-cli 2026.6.1. |

```bash
echo '{"tag":"priority"}' | celigo tags create
celigo tags create --file tag.json
```

**Corresponds to**: [`POST /v1/tags`](https://developer.celigo.com/api/api-reference/tags#post-v1-tags)

## celigo tags update

Full-replace PUT. Reads the complete tag document from `-f, --file` or stdin — omitted fields are erased.

> ⚠️ **`update` replaces the entire tag.** `PUT` erases any field you omit. `GET` the tag first, edit it, then send the complete document back — or use `set` for partial edits.

| Flag                | Description                                                                                                  |
| ------------------- | ------------------------------------------------------------------------------------------------------------ |
| `-f, --file <path>` | Read the JSON body from a file instead of stdin (`--file -` also means stdin). Added in celigo-cli 2026.6.1. |
| `--force`           | Submit even if the body contains masked credential values (`***`) copied from a GET.                         |

```bash
celigo tags update <id> --file tag.json
celigo tags update <id> < tag.json
```

**Corresponds to**: [`PUT /v1/tags/{_id}`](https://developer.celigo.com/api/api-reference/tags#put-v1-tags-_id)

## celigo tags set

Patch individual fields with `key=value` assignments. Whitelisted fields are applied via an atomic `PATCH`; other fields go through GET → modify → PUT so omitted fields are preserved. Values are auto-parsed as JSON. A `key=file://<path>` value loads that field from a file instead of the command line (a leading `~` and relative paths are supported). Added in celigo-cli 2026.6.1.

```bash
celigo tags set <id> tag="Priority - triage"
```

**Corresponds to**: [`GET /v1/tags/{_id}`](https://developer.celigo.com/api/api-reference/tags#get-v1-tags-_id) then [`PUT /v1/tags/{_id}`](https://developer.celigo.com/api/api-reference/tags#put-v1-tags-_id)

## celigo tags delete

Delete the tag. Prompts for confirmation unless `-y` is supplied.

> ⚠️ **Deleting a tag cannot be undone.** The tag is permanently removed from the account, and resources that referenced its `tagId` no longer resolve to it.

| Flag        | Description        |
| ----------- | ------------------ |
| `-y, --yes` | Skip confirmation. |

```bash
celigo tags delete <id> -y
```

**Corresponds to**: [`DELETE /v1/tags/{_id}`](https://developer.celigo.com/api/api-reference/tags#delete-v1-tags-_id)

## Gotchas

* **Two identifiers, two uses.** `_id` is the Mongo id used to `get`, `update`, `set`, and `delete` the tag itself. `tagId` is the short human code (e.g. `F3ZBQ`) that other resources reference in their `tagIds` arrays — see [`flows tag-errors`](/cli/commands/flows.md#celigo-flows-tag-errors).
* **Minimal create payload.** Only `tag` is required; the server assigns `_id` and `tagId`. Fuller fields (color, description, etc.) vary by account and are not documented in the Tags spec.

## Related

* [`flows`](/cli/commands/flows.md) — [`flows tag-errors`](/cli/commands/flows.md#celigo-flows-tag-errors) applies tag codes (`tagId`, not `_id`) to flow errors for triage; tags also surface on error records under a `tags` field.
* [`notifications`](/cli/commands/notifications.md) — notification subscriptions can target tagged resources.
* [`integrations`](/cli/commands/integrations.md) — integrations and their children can carry tags for search and filtering.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.celigo.com/cli/commands/tags.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.