# l4 tags delete

> Delete a virtual tag key and every value it assigned. Provider tags stay untouched, and a key another key reads cannot be deleted.

Source: https://docs.levelfour.ai/cli/commands/tags/delete


`l4 tags delete` deletes a virtual key, along with every value it assigned to your costs. It cannot delete a provider key: those come from your bill.

```bash
l4 tags delete <key> [--yes]
```

`<key>` is an ID or a name, as [Naming a key](/cli/commands/tags#naming-a-key) describes.

## What it changes

The command sends `DELETE /api/v1/tags/virtual/{key_id}`. Once it succeeds:

* the key and its values are gone from every month
* breakdowns, filters and recommendations stop offering the key
* your provider tags stay as they are

The API refuses with `409` `has_dependents` while another key reads this one, through a `virtual_tag` condition, a collapsed key or a cost-based source. The error lists those keys, and [`l4 tags show`](/cli/commands/tags/show) prints them under `dependents`. Change or delete them first.

> **Warning**
>
> Applying the same file again rebuilds the key, but only as far back as the backfill limit reaches. Months older than that stay without a value. [Limits](/guides/virtual-tags#limits) has the limit.

## Flags

| Flag    | Description                  |
| ------- | ---------------------------- |
| `--yes` | Skip the confirmation prompt |

Global flags (`--json`, `--jq`, `--template`, `--quiet`, `--token`, `--api`) apply. See [CLI overview](/cli#global-flags).

## Confirmation

By default the command names the key and asks for confirmation with a `[y/N]` prompt. Anything other than `y` or `yes` aborts, prints `Aborted.`, and exits `0` without calling the API. Pass `--yes` to skip the prompt.

> **Warning**
>
> Outside a terminal there is nobody to answer the prompt, so a piped or scheduled run without `--yes` exits `1` with `deleting ... outside a terminal needs --yes` and deletes nothing. It exits before anything is sent. Re-applying the file afterwards rebuilds the key only as far back as the backfill window reaches.

## Requires a read-write key

Deleting needs the `org:tags:write` permission, which a read-write key carries, and `l4 auth login` mints a read-only key. A read-only key fails with exit `1` and `permission denied: this API key lacks permission for this operation`. See [CLI authentication](/cli/authentication#browser-login-mints-a-read-only-key) for how to create a read-write key.

## Re-running it

The reference goes to the route as given, and the route resolves a virtual key by name, so a second delete answers `404` `tag_not_found` whether it named the key or its ID. Scripts that clean up keys can treat that as done.

## Examples

```bash
l4 tags delete Teams
l4 tags delete vtk_3f9a1c --yes
LEVELFOUR_TOKEN=$L4_RW_KEY l4 tags delete Teams --yes --quiet
```

## Output

Default output is a success line naming the key. The API answers `204` with no body, so script against the exit code: `0` means the key is gone. With `--json` the command prints `{"key": "<the reference you passed>", "deleted": true}`.

## Errors

| Exit | Symptom                                       | Cause                                                                  |
| ---- | --------------------------------------------- | ---------------------------------------------------------------------- |
| `4`  | Authentication required                       | No token resolvable; run `l4 auth login` or set `LEVELFOUR_TOKEN`      |
| `1`  | `401` authentication failed                   | Token revoked, expired, or from the wrong environment                  |
| `1`  | `403` permission denied                       | The key is read-only, or your role lacks `org:tags:write`              |
| `1`  | `no virtual tag key named ...`                | A name nobody holds, resolved locally against the key list             |
| `1`  | `... is a provider tag key`                   | A `ptk_` ID or a provider key's name. Provider tags come from the bill |
| `1`  | `404` `tag_not_found`                         | A `vtk_` ID nobody holds                                               |
| `1`  | `deleting ... outside a terminal needs --yes` | No TTY to confirm on, and no `--yes`                                   |
| `1`  | `409` `has_dependents`                        | Another key reads this one. The error names it                         |

## Related

* [`l4 tags show`](/cli/commands/tags/show): check `dependents` before you delete
* [`l4 tags apply`](/cli/commands/tags/apply): recreate a key from its file
* [CLI authentication](/cli/authentication): read versus read-write keys