--- title: tags description: Manage Workspace tag names and colors. canonical_url: https://orchestor.io/docs/en/cli/tag markdown_url: https://orchestor.io/docs/en/cli/tag.md contentType: reference --- # tags `orc tags` manages tags used to organize questions in a Workspace. Retrieve a list, create or update names and display colors, or soft-delete tags. Authentication and access to the target Workspace are required. Use tag IDs returned by listing for updates and deletion. Attach tags to questions through [`orc prompts tags update`](https://orchestor.io/docs/cli/prompt.md); attachment is separate from creating a tag. ## Usage ```bash title="terminal" orc tags list --workspace ``` *Inspect tags and their IDs.* ## Subcommands ### `list` List Workspace tags. Use `--limit` and returned cursors for pagination. ```bash title="terminal" orc tags list [options] ``` ### `create` `name` is required and limited to 64 characters. Optional `color` uses a registered color name. Use `--idempotency-key` for retries. ```bash title="terminal" orc tags create [options] ``` #### Unique options ##### `--idempotency-key` Retry identity for operations that support idempotency. Use a unique key for each new operation, and reuse it only when retrying the same HTTP method, path, query values and exact request body. JSON whitespace changes can count as a different body. Keys contain 1–255 characters after trimming and expire after 24 hours. A completed JSON response is replayed without repeating the operation. A different request using the same key returns 409 idempotency_error. An in-progress request returns 409 idempotency_in_progress with Retry-After: 2. Whether this header is required depends on the operation. Type: `string`. Optional. ```bash title="terminal" orc tags create --idempotency-key ``` ##### `--name` (required) Tag name, from 1 to 64 characters. Must be unique among active tags in this workspace, ignoring case.; max 64 chars Type: `string`. Optional. ```bash title="terminal" orc tags create --name ``` ##### `--color` Display color token. Defaults to gray when omitted.; enum: gray|red|orange|yellow|lime|green|cyan|blue|purple|fuchsia|pink|emerald|amber|violet|indigo|teal|sky|rose|slate|zinc|neutral|stone Type: `string`. Optional. ```bash title="terminal" orc tags create --color ``` #### Examples ```bash title="terminal" orc tags create --name "Priority" --color blue --workspace ``` *Create a tag with a display color* ### `update` Update supplied `name` and `color` by tag ID. Clear the color with `--color null` or `--color reset`. ```bash title="terminal" orc tags update [options] ``` #### Unique options ##### `--idempotency-key` Retry identity for operations that support idempotency. Use a unique key for each new operation, and reuse it only when retrying the same HTTP method, path, query values and exact request body. JSON whitespace changes can count as a different body. Keys contain 1–255 characters after trimming and expire after 24 hours. A completed JSON response is replayed without repeating the operation. A different request using the same key returns 409 idempotency_error. An in-progress request returns 409 idempotency_in_progress with Retry-After: 2. Whether this header is required depends on the operation. Type: `string`. Optional. ```bash title="terminal" orc tags update --idempotency-key ``` ##### `--name` Replacement tag name. Omit to retain the current name.; max 64 chars Type: `string`. Optional. ```bash title="terminal" orc tags update --name ``` ##### `--color` Replacement color token. Send null to clear the stored color; omit to retain it.; enum: |gray|red|orange|yellow|lime|green|cyan|blue|purple|fuchsia|pink|emerald|amber|violet|indigo|teal|sky|rose|slate|zinc|neutral|stone; (use "null" or "reset" to clear) Type: `string`. Optional. ```bash title="terminal" orc tags update --color ``` #### Examples ```bash title="terminal" orc tags update --color null --workspace ``` *Clear a tag’s display color* ### `delete` Soft-delete a tag by ID. Check the target Workspace and ID first. ```bash title="terminal" orc tags delete [options] ``` ## Colors and question associations Colors are `gray`, `red`, `orange`, `yellow`, `lime`, `green`, `cyan`, `blue`, `purple`, `fuchsia`, `pink`, `emerald`, `amber`, `violet`, `indigo`, `teal`, `sky`, `rose`, `slate`, `zinc`, `neutral`, and `stone`. `prompts tags update` replaces all associations, so include existing tag IDs you want to preserve along with the new tag. A tag name cannot be used as the prompt ID argument. ## Permissions Access to the target Workspace is required. Changes require the corresponding write permissions. ## Global Options The following [global options](https://orchestor.io/docs/cli/global-flags.md) can be used with `orc tags`: - [`--help`](https://orchestor.io/docs/cli/global-flags.md#help) - [`--workspace`](https://orchestor.io/docs/cli/global-flags.md#workspace) - [`--json`](https://orchestor.io/docs/cli/global-flags.md#json-output) - [`--pretty`](https://orchestor.io/docs/cli/global-flags.md#json-output) - [`--format`](https://orchestor.io/docs/cli/global-flags.md#output-format) - [`--field`](https://orchestor.io/docs/cli/global-flags.md#field-selection) - [`--fields`](https://orchestor.io/docs/cli/global-flags.md#field-selection) - [`--raw`](https://orchestor.io/docs/cli/global-flags.md#raw-output) - [`--output`](https://orchestor.io/docs/cli/global-flags.md#file-output) - [`--no-pager`](https://orchestor.io/docs/cli/global-flags.md#pager) - [`--dry-run`](https://orchestor.io/docs/cli/global-flags.md#dry-run) - [`--yes`](https://orchestor.io/docs/cli/global-flags.md#confirmation) - [`--limit`](https://orchestor.io/docs/cli/global-flags.md) - [`--cursor`](https://orchestor.io/docs/cli/global-flags.md) - [`--stdin`](https://orchestor.io/docs/cli/global-flags.md#standard-input) - [`--from-stdin`](https://orchestor.io/docs/cli/global-flags.md#standard-input) - [`--page-all`](https://orchestor.io/docs/cli/global-flags.md#all-pages) - [`--timing`](https://orchestor.io/docs/cli/global-flags.md#request-timing) - [`--readonly`](https://orchestor.io/docs/cli/global-flags.md#read-only-mode) - [`--wrap-untrusted`](https://orchestor.io/docs/cli/global-flags.md#untrusted-content-wrapping) For details and examples, see [global options](https://orchestor.io/docs/cli/global-flags.md). --- [Documentation index](https://orchestor.io/docs/llms.txt)