baseten volume stat and baseten volume versions show a volume’s tags. baseten volume ls shows the tags in a namespace.
A volume reference starts with bdn:<namespace>/<volume>. It can include a :<tag> or @<digest> selector and a trailing path, as in bdn:weights/llama:prod/config/model.json. You must include the bdn: prefix. Without a selector, the reference uses the volume’s head version. Write a digest with or without its b3: prefix and shorten it to 12 or more hexadecimal characters.
set
--tag to the version selected by --volume-ref. The command creates a tag that doesn’t exist. A volume reference without a selector uses the head version. A :<tag> or @<digest> selector uses that version. Don’t include a path because a tag names an entire version.
Setting a tag that already exists overwrites it. Pass --expires-at to make the tag expire at that time. Setting it again without --expires-at clears the tag’s expiration time. The tag is still removed if its version or volume expires.
--tag can be head. Setting it changes which version a reference without a tag or digest resolves to. head can’t use --expires-at or point to an expiring version. Setting head prompts for confirmation unless you pass --yes.
Options
TEXT
Time at which the tag expires, as an RFC 3339 date-time with a UTC offset, as in 2030-01-01T00:00:00Z. It must be in the future and at most ten years ahead. Omit it for a tag that does not expire. Omitting it on an existing tag clears its expiration time.
BOOL
Write refs with the whole digest instead of shortening it to 12 hex characters.
TEXT
Filter JSON output with a jq expression; implies —output json (or jsonl for streamed commands)
TEXT
default:"text"
Output formatOne of:
text, json, jsonl, noneTEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
TEXT
required
Tag to point at the version. May be ‘head’.
TEXT
required
Ref of the version to tag, as bdn:
namespace/volume for the version head points at, or with a :tag or @digest selector for that version.BOOL
Skip confirmation for ‘head’. Required when stdin is not a terminal and —tag is ‘head’.
BOOL
Enable verbose logging
Examples
Point a tag at a versionFilter output with --jq
Print the ref of the version the tag now points at, pinned to its digest
Output
Text mode (--output text): One field per line: the ref of the version the tag now points at, the tag, the digest, when the tag expires, and the volume’s sequence.
JSON mode (--output json): Returns the tag, digest, pinned version reference, expiration, and volume sequence.
delete
--tag from the volume named by --volume-ref. The version remains reachable by digest and by any other tag. Deleting a tag that doesn’t exist succeeds and reports that the command made no change.
--volume-ref must name a volume without a selector or path because a tag belongs to the volume, not to one version. Deleting head prevents references without a tag or digest from resolving until you set head again. Deleting head prompts for confirmation unless you pass --yes.
Options
TEXT
Filter JSON output with a jq expression; implies —output json (or jsonl for streamed commands)
TEXT
default:"text"
Output formatOne of:
text, json, jsonl, noneTEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
TEXT
required
Name of the tag to delete.
TEXT
required
Ref of the volume the tag belongs to, as bdn:
namespace/volume, with no selector and no path.BOOL
Skip confirmation for ‘head’. Required when stdin is not a terminal and —tag is ‘head’.
BOOL
Enable verbose logging
Examples
Delete a tagFilter output with --jq
Print whether the tag existed
Output
Text mode (--output text): One field per line: the tag, whether the command deleted it, and the volume’s sequence.
JSON mode (--output json): Returns the tag, whether the command deleted it, and the volume sequence.