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

# Environment Tags

> Tag env zero environments with key-value pairs, then find them by tag in Explorer or the project environments list and act on them in bulk.

Tags are key-value metadata you attach to an environment, for example `team=payments` or `cost-center=1042`. Use them to record ownership, cost attribution, or any other classification your project hierarchy does not express, then find environments by tag and act on them in bulk.

A tag key holds one or more values. An environment tagged `team=payments` and `team=platform` carries one key with two values, and each pair renders as its own chip.

Project tags are a separate, simpler feature: plain labels with no keys and no values.

<Warning>
  Anyone who can view an environment can read its tags. Do not put secrets or personal data in tags. Use [variables](/guides/admin-guide/variables) for values that must stay hidden.
</Warning>

## Limits

| Constraint                      | Value                                                                                          |
| ------------------------------- | ---------------------------------------------------------------------------------------------- |
| Key-value pairs per environment | 50. A key holding three values counts as three pairs.                                          |
| Key length                      | 1 to 128 characters                                                                            |
| Value length                    | 1 to 256 characters                                                                            |
| Allowed characters              | Letters, digits, spaces, and `_ . : / + - @`. `=` and `,` are not allowed in a key or a value. |
| Values within a key             | Must be unique                                                                                 |

Editing tags requires the **Edit Environment Settings** permission, the same permission that gates every other environment setting. Without it, the environment's tags are shown as read-only chips.

## Edit an environment's tags

<Steps>
  <Step title="Open the environment's settings">
    From the **Project Environments** tab, click the environment, then open the **Settings** tab and scroll to the **Tags** card.
  </Step>

  <Step title="Add a tag">
    Click **+ New tag** and type the key in the left field.
  </Step>

  <Step title="Add values">
    In the values field, type a value and press Enter. Repeat for as many values as the key needs. Values already used with that key elsewhere in your organization appear as options, and **Add all** applies every one of them at once.
  </Step>

  <Step title="Save">
    The counter under the editor shows how many of the 50 pairs you have used. Click **Save** to apply the changes.
  </Step>
</Steps>

Click the trash icon on a row to remove a tag and all of its values. Invalid rows are highlighted with the reason, and saving is blocked until they are fixed.

## Find environments by tag

Tags appear in two places, and each one searches differently.

### Project environments list

Each environment card shows up to four tag chips, with a `+N` chip for the rest. The search box at the top of the list matches tags along with names, templates, and statuses, so typing `payments` returns environments tagged `team=payments`.

### Explorer

The [Explorer](/guides/cloud-analyst/cloud-analyst/explorer) table has a **tags** column with its own filter. Open the filter and tick one or more `key=value` pairs, and the table narrows to environments carrying any of the ticked pairs. The filter has a search box, so you can type to find a pair in a long list.

Explorer covers every active environment in your organization across projects, and its filter selection persists in the page URL, so a tag-filtered view is a link you can share.

<Info>
  Explorer lists active environments. To find tags on inactive environments, use the [API](/api-reference).
</Info>

## Add and remove tags in bulk

The [bulk operations](/guides/admin-guide/environments/bulk-operations) wizard has two tag commands. Filter Explorer by tag, or select environments from the project environments list, then click **Perform Action** and pick a command.

**Add Tags** applies the same tags to every selected environment. Fill in keys and values with the same editor used in environment settings. A key that already exists on an environment has its values replaced, and keys you do not list are left untouched.

**Remove Tags** takes a list of keys and removes each one from every selected environment, values and all. A key an environment does not carry is skipped.

Both commands require the **Edit Environment Settings** permission on each selected environment. The wizard's summary step marks environments you cannot edit with a failure icon and skips them. The rest of the selection is processed.

## Next steps

* [Managing Bulk Operations](/guides/admin-guide/environments/bulk-operations) - Run deploy, destroy, and other actions across many environments.
* [Explorer](/guides/cloud-analyst/cloud-analyst/explorer) - Search and manage all environments in one view.
* [Environment Overview](/guides/admin-guide/environments) - All actions available on an individual environment.