l4 tags apply

l4 tags apply makes a virtual key in LevelFour match a YAML file. When no virtual key has the file's name, it creates one. When one does, the file replaces that key's whole definition. The command prints the difference before it sends anything.

l4 tags apply -f <file> [flags]

What it changes

The command reads GET /api/v1/tags/keys to find a virtual key named like the file, then:

• with no such key, posts the file to /api/v1/tags/virtual and creates one
• with one whose rules the file changes, sends PUT /api/v1/tags/virtual/{key_id} with the whole file, and the key's rules_version as expected_version
• with one whose rules the file leaves alone, sends PATCH /api/v1/tags/virtual/{key_id} with the settings that moved, so editing a description does not reprocess a year of spend

The file replaces the definition, so a config you removed from the file is gone from the key once the command finishes. A change to the configs, the collapsed keys, can_override or effective_from starts a job that reprocesses the key from effective_from to the current month, and the key reads reprocessing until it ends.

File format

A tag file describes one virtual key. l4 tags preview reads the same format.

name: Teams
description: Owning team across AWS and GCP.
effective_from: "2026-06"        # optional, YYYY-MM; omitted = current month
can_override: false               # optional
collapsed_keys:                   # optional, in priority order
  - source: {origin: provider, key: owner}
    providers: [aws]              # optional scope
    prefix: ""                    # optional value prefix
configs:                          # in priority order, first match wins
  - value: data
    rules:
      - providers: [aws, gcp]
        where:
          - {dimension: service, operator: is, values: [Amazon Redshift, BigQuery]}
  - value: team-a
    rules:
      - providers: [aws, gcp]
        where:
          - {dimension: tag, key: team, operator: flexible_match, values: [Team A]}
  - split:
      - {value: infra, pct: 60}
      - {value: mobile, pct: 40}
    rules:
      - providers: [aws]
        where:
          - {dimension: account, operator: is, values: ["999900001111"]}
  - cost_based:
      source: {origin: provider, key: team}
      input:
        - providers: [aws]
          where:
            - {dimension: charge_type, operator: is, values: [Usage]}
    rules:
      - providers: [aws]
        where:
          - {dimension: service, operator: starts_with, values: [AWS Support]}
    time_frame: {start: "2026-07-01"}   # optional

l4 rejects a field it does not recognise, so a typo such as condition: for where: fails the command instead of dropping the rule. Virtual tags has the dimensions, the operators, and a worked example for each kind of config.

Flags

Global flags (--json, --jq, --template, --quiet, --token, --api) apply. See CLI overview.

Dry run

--dry-run reads the saved key, prints the difference and stops. It only reads, so a read-only key can run it. The exit code says what it found:

Run it on each pull request that touches a tag file, and the pipeline fails whenever the saved key and the file disagree:

l4 tags apply -f tags/teams.yaml --dry-run --quiet

Confirmation

By default, the command prints the difference, then asks for confirmation with a [y/N] prompt. Anything other than y or yes aborts, prints Aborted., and exits 0 without sending the change. Pass --yes to skip the prompt in an interactive shell. When the file matches the saved key, there is nothing to confirm and nothing is sent.

Requires a read-write key

Writes need 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 for how to create a read-write key.

Re-running it

A second run with the same file finds no difference and sends nothing. The file wins over the dashboard: a run after someone edited the key there replaces their edit, and the printed difference shows what it undoes.

If someone changes the key between the command's read and its write, the API answers 409 version_conflict and saves nothing. Run apply again to diff against the new version.

Examples

l4 tags apply -f teams.yaml
l4 tags apply -f teams.yaml --dry-run
l4 tags apply -f teams.yaml --yes --json
LEVELFOUR_TOKEN=$L4_RW_KEY l4 tags apply -f teams.yaml --yes --quiet

Apply several files in order, with the key that another one reads going first:

for f in tags/applications.yaml tags/business-units.yaml; do
  l4 tags apply -f "$f" --yes || exit 1
done

Output

Default output is the difference, then a success line naming the key and the reprocessing job. With --json the whole API envelope is printed. The fields it carries:

.success
.data.key                    # the key as l4 tags show --json prints it
.data.key.id
.data.key.rules_version
.data.key.status             # "reprocessing" while the job runs
.data.job                    # null when nothing needs reprocessing
.data.job.id
.data.job.status             # "queued" or "running" right after a change
.data.job.from_period
.data.job.to_period
.timestamp

--dry-run --json prints the plan instead of an API envelope: action (create, update or none), key_id on an existing key, and definition, the body the real run would send.

Validation problems

A file that breaks a rule fails with 422 validation_failed, and the error lists every problem at once. Each problem carries a code and, where one applies, the position of the config, rule, condition, split or collapsed key at fault. The API counts those from 0 and the CLI prints them from 1, matching how l4 tags show numbers configs. The codes a file author meets most:

The Tags API reference lists every code.

Errors

Related

• l4 tags preview: try the file before you apply it
• l4 tags show: the saved key and its reprocessing job
• l4 tags delete: remove a key
• Virtual tags: worked examples for every kind of config
• CLI authentication: read versus read-write keys