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

# vers tag

> Named pointers to commits. Move them, list them, delete them — commits are unaffected.

`vers tag` is Vers' analogue of `git tag`: a human-readable name pointing to a commit. Tags are mutable (you can move them with `tag update`) and cheap (deleting a tag doesn't touch the commit it points to).

`vers build -t`, `vers run-commit`, and `vers build`'s `FROM` clause all accept tag names anywhere a commit id is expected.

## Synopsis

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers tag create <name> <commit-id> [-d "description"]
vers tag list                                     # Human-readable
vers tag list -q                                  # Just names
vers tag list --format json                       # Machine-readable
vers tag get <name>
vers tag update <name> --commit <new-commit>      # Move tag
vers tag update <name> --description "..."        # Update description
vers tag delete <name> [<name>...]
```

## Subcommands

### `vers tag create`

Create a tag pointing to a commit.

<Info>
  **Naming rules**: alphanumeric characters plus `-`, `_`, `.`; 1–64 characters.
</Info>

| Option              | Description          |
| ------------------- | -------------------- |
| `-d, --description` | Optional description |

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers tag create production abc-123
vers tag create v1.2 abc-123 -d "First stable release"
```

### `vers tag list`

List all tags in your organization.

| Option          | Description              |
| --------------- | ------------------------ |
| `-q, --quiet`   | Just names, one per line |
| `--format json` | Machine-readable output  |

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers tag list
vers tag list -q
vers tag list --format json | jq '.[] | {name, commit_id}'
```

### `vers tag get`

Show details for a single tag.

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers tag get production
vers tag get production --format json
```

### `vers tag update`

Move a tag or update its description. At least one of `--commit` or `--description` is required.

| Option              | Description               |
| ------------------- | ------------------------- |
| `--commit`          | New commit id to point at |
| `-d, --description` | New description           |

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# Promote a newer commit to production
vers tag update production --commit def-456

# Update the description in place
vers tag update production --description "Post-launch hotfix"
```

### `vers tag delete`

Delete one or more tags. Commits they pointed at are unaffected.

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers tag delete staging
vers tag delete staging preview
vers tag delete $(vers tag list -q)   # nuke all tags
```

## Examples

### Name your build outputs

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers build -t myapp:prod .             # -t calls tag create under the hood
vers run-commit myapp:prod             # Boot the latest prod build
```

### Promote through environments

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
COMMIT=$(vers build -q .)
vers tag create staging "$COMMIT"

# ...testing...

vers tag update production --commit "$COMMIT"
```

### Branch off a named tag

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers branch production                 # Branch directly off the tag
```

## Common Patterns

### Tag the latest build

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
COMMIT=$(vers build -q .)
vers tag update latest --commit "$COMMIT"
```

### Promote through environments

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
COMMIT=$(vers build -q .)
vers tag update staging    --commit "$COMMIT"
# ...after testing...
vers tag update production --commit "$COMMIT"
```

### Delete all test tags

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers tag delete $(vers tag list -q | grep '^test-')
```

### Pin a release

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
COMMIT=$(vers commit --format json | jq -r .commit_id)
vers tag create v1.2.0 "$COMMIT" -d "stable release, build $(date -u +%Y-%m-%dT%H:%M:%SZ)"
```

## See also

* [vers commit](/cli-reference/commit) — create the commits tags point to
* [vers build](/cli-reference/build) — build a commit and tag it in one step with `-t`
* [vers run-commit](/cli-reference/run-commit) — boot a commit or tag
* [vers branch](/cli-reference/branch) — branch from a commit or tag