# l4 tags preview

> Dry-run a virtual tag file against your recent costs. Shows the spend each value would take and the spend left unallocated, and stores nothing.

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


`l4 tags preview` runs a tag file against your recent costs and prints what each value would take. It saves nothing, so you can try a rule, read the result and edit the file as many times as you like before [`l4 tags apply`](/cli/commands/tags/apply).

```bash
l4 tags preview -f <file> [--start <date> --end <date>]
```

The command posts the file to `/api/v1/tags/virtual/preview`. It reads the same [file format](/cli/commands/tags/apply#file-format) as `apply`, and `name` may be empty.

> **Note**
>
> Preview evaluates the file you pass, not the saved key. `effective_from` has no effect here: the window is `--start` to `--end`, or the last 30 complete days, and [Limits](/guides/virtual-tags#limits) caps its length.

## Flags

| Flag                              | Description                                   |
| --------------------------------- | --------------------------------------------- |
| `-f <file>`                       | Tag file to evaluate. Required                |
| `--start <date>` / `--end <date>` | Window. See [Dates](/cli/commands/tags#dates) |

Global flags apply. See [CLI overview](/cli#global-flags).

## Examples

```bash
l4 tags preview -f teams.yaml
l4 tags preview -f teams.yaml --start 2026-08-01 --end 2026-08-31
l4 tags preview -f teams.yaml --jq '.data.unallocated_spend'
l4 tags preview -f teams.yaml --jq '.data.values[] | [.name, .spend]'
```

## Output

Default output is a table of values with their spend and resource count, followed by the unallocated and shadowed spend. With `--json` the whole API envelope is printed. The fields it carries:

```text
.data.window.start
.data.window.end
.data.total_spend
.data.unallocated_spend
.data.shadowed_spend         # spend a lower config also matches, already taken by a higher one
.data.values[].name
.data.values[].spend
.data.values[].resource_count
.data.values[].sample_resources[]
```

`shadowed_spend` points at order problems. A config you expected to claim spend, showing little of it while `shadowed_spend` is high, sits below a broader config that takes its lines first. Move it up.

## Errors

| Exit | Symptom                                          | Cause                                                                                                       |
| ---- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| `4`  | Authentication required                          | No token resolvable; run `l4 auth login` or set `LEVELFOUR_TOKEN`                                           |
| `1`  | The file does not parse, or has an unknown field | Fix the file. [File format](/cli/commands/tags/apply#file-format) lists the fields                          |
| `1`  | `401` authentication failed                      | Token revoked, expired, or from the wrong environment                                                       |
| `1`  | `422` `validation_failed`                        | The file breaks a rule. [Validation problems](/cli/commands/tags/apply#validation-problems) lists the codes |

## Related

* [`l4 tags apply`](/cli/commands/tags/apply): save the file once the preview looks right
* [Virtual tags](/guides/virtual-tags): the rules the preview evaluates