libra tag

Create, list, or delete tags.

Synopsis

libra tag [<name>] [-m <message> | -F <file>] [-e] [-f] [-s]
libra tag -l [-n <lines>] [--points-at <object>] [--contains <commit>] [--merged <commit>] [--sort <key>] [--column[=<mode>]]
libra tag -v <name>
libra tag -d <name>

Description

libra tag manages lightweight and annotated tags. A lightweight tag is simply a named pointer to a commit, while an annotated tag stores a full tag object with a message, tagger identity, and timestamp.

Without arguments (or with -l), the command lists all tags. When given a name, it creates a new tag at HEAD. Adding -m <message> (or -F <file>, reading the message from a file or stdin) creates an annotated tag instead of a lightweight one; -e/--edit composes the message in an editor (pre-filled by -m/-F when present), and since Libra has no separate -a, -e is also a create-only annotated-tag path. The -f flag allows overwriting an existing tag of the same name.

Tag references are stored in the SQLite database alongside branch references, providing the same transactional guarantees.

Options

Flag examples

# Create a lightweight tag at HEAD
libra tag v1.0

# Create an annotated tag with a message
libra tag -m "Release v1.1" v1.1

# Create an annotated tag, reading the message from a file (or stdin with -)
libra tag -F release-notes.txt v1.1
libra log -1 --format=%B | libra tag -F - v1.1

# Force-overwrite an existing tag
libra tag -f v1.0

# List all tags
libra tag -l

# List tags with annotation preview (2 lines)
libra tag -l -n 2

# List only tags pointing at HEAD's commit
libra tag --points-at HEAD

# Delete a tag
libra tag -d v1.0

# JSON output for agents
libra tag --json v1.0

Common Commands

libra tag v1.0                        # Create a lightweight tag at HEAD
libra tag -m "Release v1.1" v1.1      # Create an annotated tag
libra tag -l -n 2                     # List tags with up to 2 annotation lines
libra tag --points-at HEAD            # List tags pointing at HEAD's commit
libra tag -d v1.0                     # Delete a tag
libra tag --json v1.0                 # Structured JSON output for agents

Human Output

• libra tag -l: prints the tag list, one per line; with -n shows annotation lines indented
• libra tag v1.0: Created lightweight tag 'v1.0' at abc1234
• libra tag -m "msg" v1.0: Created annotated tag 'v1.0' at abc1234
• libra tag -d v1.0: Deleted tag 'v1.0' (was abc1234)
• The default create path preserves the current human-readable output

Structured Output (JSON examples)

--json / --machine uses action to distinguish operations:

Create a tag:

{
  "ok": true,
  "command": "tag",
  "data": {
    "action": "create",
    "name": "v1.0",
    "hash": "abc123...",
    "tag_type": "lightweight",
    "message": null
  }
}

Create an annotated tag:

{
  "ok": true,
  "command": "tag",
  "data": {
    "action": "create",
    "name": "v1.1",
    "hash": "abc123...",
    "tag_type": "annotated",
    "message": "Release v1.1"
  }
}

List tags:

{
  "ok": true,
  "command": "tag",
  "data": {
    "action": "list",
    "tags": [
      { "name": "v1.0", "hash": "abc123...", "tag_type": "lightweight", "message": null },
      { "name": "v1.1", "hash": "def456...", "tag_type": "annotated", "message": "Release v1.1" }
    ]
  }
}

Delete a tag:

{
  "ok": true,
  "command": "tag",
  "data": {
    "action": "delete",
    "name": "v1.0",
    "hash": "abc123..."
  }
}

action=list returns a tags array; action=delete returns name and hash. For recovery deletes of malformed tag refs, hash can be null when the stored target is missing.

Design Rationale

Why vault PGP signing instead of GPG?

libra tag -s signs an annotated tag and libra tag -v verifies it, but both go through a vault PGP key rather than a local GPG keyring. The mechanism differs from Git's GPG signing on purpose:

• GPG key management is fragile: developers frequently lose keys, let them expire, or misconfigure gpg-agent, leading to broken signing workflows. In CI/CD environments, managing GPG keyrings securely is an operational burden.
• Vault-based signing is the intended path: signing keys live in Libra's vault (see --vault on libra init) so cryptographic operations are delegated to a secure key store rather than requiring each developer to maintain local GPG keys. This centralizes trust and simplifies key rotation.
• Not Git-interoperable: because the armored signature is produced and checked through the vault PGP path, libra tag -s is not bit-compatible with git tag -s/git tag -v. A tag signed in Libra verifies with libra tag -v, not with Git's GPG verification, and vice versa.

Signing requires -m (clap requires = "message"); -e can then further edit that -m message, but -s does not accept -F or an editor-only message. libra tag -v <name> exits 0 for a good signature and 1 for a bad one; unsigned, non-annotated, or missing tags report a clear error.

Why lightweight vs annotated distinction?

Libra preserves Git's two-tier tag model for on-disk format compatibility. Lightweight tags are simple ref pointers (ideal for temporary markers), while annotated tags store metadata useful for releases. A message source is the toggle: providing -m, -F, or -e (which composes the message in an editor) creates an annotated tag, its absence creates a lightweight one. Because Libra has no separate -a, -e is the editor-driven way to create an annotated tag (Git would need -a/-m/-F alongside -e) — otherwise the two-tier model matches Git, keeping the mental model consistent for users migrating from Git.

Parameter Comparison: Libra vs Git vs jj

Error Handling