Tag and Tag Type Commands

Manage tags and tag types for organizing and categorizing assets in VAMS. Tags belong to tag types, which define classification categories. Tag types must exist before tags can reference them.

Tag scope

Tags and tag types are either GLOBAL (available in every database) or scoped to one database. Omit --database to work with GLOBAL entries; pass --database <id> to scope to that database. Names are unique per database, so the same name may exist in several databases — but a name cannot be both GLOBAL and database-specific.

On the list commands, --database returns only that database's entries; GLOBAL entries are not included. Use --scope global for GLOBAL only, or --scope all for everything. An asset resolves its tag names within its own database plus GLOBAL.

note

Both tag and tag-type create and update commands accept --json-input for batch operations. The value is either a JSON string or a path to a .json file (no @ prefix). Batch operations are processed in a single request.

---

tag create

Create one or more tags in VAMS.

vamscli tag create [OPTIONS]

Option	Type	Required	Description
--tag-name	TEXT	Conditional	Tag name (required unless using --json-input)
--description	TEXT	Conditional	Tag description (required unless using --json-input)
--tag-type-name	TEXT	Conditional	Tag type name (required unless using --json-input)
--json-input	TEXT	No	JSON string or path to a JSON file with tag data (batch)
--database	TEXT	No	Scope the tag to this database (omit for a GLOBAL tag)
--json-output	Flag	No	Output raw JSON response

When --json-input is not used, --tag-name, --description, and --tag-type-name are all required. The referenced tag type must already exist.

The JSON input is a single flat tag object:

{
    "tagName": "urgent",
    "description": "Urgent priority",
    "tagTypeName": "priority"
}

vamscli tag create --tag-name "urgent" --description "Urgent priority" --tag-type-name "priority"
vamscli tag create --json-input '{"tagName":"urgent","description":"Urgent","tagTypeName":"priority"}'
vamscli tag create --json-input tags.json --json-output

---

tag update

Update an existing tag's description and/or tag type.

vamscli tag update [OPTIONS]

Option	Type	Required	Description
--tag-name	TEXT	Conditional	Tag name to update (required unless using --json-input)
--description	TEXT	No	New tag description
--tag-type-name	TEXT	No	New tag type name
--json-input	TEXT	No	JSON string or path to a JSON file with tag data (batch)
--database	TEXT	No	Scope the tag to this database (omit for a GLOBAL tag)
--json-output	Flag	No	Output raw JSON response

When not using --json-input, --tag-name is required and at least one of --description or --tag-type-name must be provided. The command retrieves the current tag first and preserves any field not supplied.

vamscli tag update --tag-name "urgent" --description "Updated description"
vamscli tag update --tag-name "urgent" --tag-type-name "new-priority"
vamscli tag update --json-input '{"tagName":"urgent","description":"Updated","tagTypeName":"priority"}'

---

tag delete

Permanently delete a tag from VAMS.

vamscli tag delete <TAG_NAME> [OPTIONS]

Option	Type	Required	Description
TAG_NAME	TEXT	Yes	Tag name to delete (positional)
--confirm	Flag	Yes	Confirm deletion
--database	TEXT	No	The database the tag is scoped to (omit for a GLOBAL tag)
--json-output	Flag	No	Output raw JSON response

Confirmation required

The --confirm flag is required to prevent accidental deletions. Without it, the command exits with an error.

vamscli tag delete urgent --confirm
vamscli tag delete urgent --confirm --json-output

---

tag list

List all tags, optionally filtered by tag type.

vamscli tag list [OPTIONS]

Option	Type	Required	Description
--tag-type	TEXT	No	Filter tags by tag type name (case-insensitive)
--database	TEXT	No	Show only tags scoped to this database (GLOBAL tags excluded)
--scope	TEXT	No	global for GLOBAL tags only, all for every tag
--json-output	Flag	No	Output raw JSON response

The default output is a table of tag name, tag type, and description. Tags belonging to a required tag type are shown with an [R] indicator on the tag type.

--tag-type filters the payload rather than the display, so --json-output returns the same narrowed set the table shows.

The listing returns the whole tag vocabulary in one call. --database <id> and --scope global read a single partition and always return it complete; the unscoped form is bounded at the service's item limit, and if that limit is reached the output says so and points at the two scoped forms.

vamscli tag list
vamscli tag list --tag-type priority
vamscli tag list --json-output

---

tag-type create

Create one or more tag types in VAMS.

vamscli tag-type create [OPTIONS]

Option	Type	Required	Description
--tag-type-name	TEXT	Conditional	Tag type name (required unless using --json-input)
--description	TEXT	Conditional	Tag type description (required unless using --json-input)
--required	Flag	No	Mark this tag type as required for asset classification
--json-input	TEXT	No	JSON string or path to a JSON file with tag type data
--database	TEXT	No	Scope the tag type to this database (omit for GLOBAL)
--json-output	Flag	No	Output raw JSON response

When --json-input is not used, --tag-type-name and --description are both required. When --json-input is supplied, it provides the tag type data directly and the individual options are not required.

A tag type created with --required takes effect once it has tags. Until then it does not constrain asset creation or updates, so a required tag type can be defined before its tags are added.

The JSON input is a single flat tag type object, where the required field is the string "True" or "False":

{
    "tagTypeName": "priority",
    "description": "Priority levels",
    "required": "True"
}

vamscli tag-type create --tag-type-name "priority" --description "Priority levels"
vamscli tag-type create --tag-type-name "status" --description "Processing status" --required
vamscli tag-type create --json-input '{"tagTypeName":"priority","description":"Priority levels","required":"True"}'
vamscli tag-type create --json-input tag-types.json --json-output

---

tag-type update

Update an existing tag type's description and/or required flag.

vamscli tag-type update [OPTIONS]

Option	Type	Required	Description
--tag-type-name	TEXT	Conditional	Tag type name to update (required unless using --json-input)
--description	TEXT	No	New tag type description
--required / --not-required	Flag	No	Update the required flag
--json-input	TEXT	No	JSON string or path to a JSON file with tag type data
--database	TEXT	No	Scope the tag type to this database (omit for GLOBAL)
--json-output	Flag	No	Output raw JSON response

When not using --json-input, --tag-type-name is required and at least one of --description or --required / --not-required must be provided. The command retrieves the current tag type first and preserves any field not supplied.

vamscli tag-type update --tag-type-name "priority" --description "Updated description"
vamscli tag-type update --tag-type-name "priority" --required
vamscli tag-type update --tag-type-name "priority" --not-required
vamscli tag-type update --json-input '{"tagTypeName":"priority","description":"Updated","required":"True"}'

---

tag-type delete

Permanently delete a tag type from VAMS.

vamscli tag-type delete <TAG_TYPE_NAME> [OPTIONS]

Option	Type	Required	Description
TAG_TYPE_NAME	TEXT	Yes	Tag type name to delete (positional)
--confirm	Flag	Yes	Confirm deletion
--database	TEXT	No	The database the tag is scoped to (omit for a GLOBAL tag)
--json-output	Flag	No	Output raw JSON response

Confirmation required

The --confirm flag is required to prevent accidental deletions. A tag type that is currently in use by one or more tags cannot be deleted; delete those tags first.

vamscli tag-type delete priority --confirm
vamscli tag-type delete priority --confirm --json-output

---

tag-type list

List all tag types, optionally including the tags associated with each type.

vamscli tag-type list [OPTIONS]

Option	Type	Required	Description
--show-tags	Flag	No	Include associated tags in a detailed view
--database	TEXT	No	Show only tag types scoped to this database (GLOBAL excluded)
--scope	TEXT	No	global for GLOBAL tag types only, all for every tag type
--json-output	Flag	No	Output raw JSON response

The default output is a table of name, description, required status, and tag count. Adding --show-tags switches to a detailed view that lists the tags associated with each tag type.

As with tag list, --database <id> and --scope global read a single partition and always return it complete; the unscoped form is bounded at the service's item limit.

vamscli tag-type list
vamscli tag-type list --show-tags
vamscli tag-type list --json-output

---

Workflow Example

Create tag types before the tags that reference them, then verify the result.

# Create tag types first
vamscli tag-type create --tag-type-name "priority" --description "Priority levels" --required
vamscli tag-type create --tag-type-name "category" --description "Asset categories"

# Create tags for each type
vamscli tag create --tag-name "urgent" --description "Urgent priority" --tag-type-name "priority"
vamscli tag create --tag-name "model" --description "3D models" --tag-type-name "category"

# Verify
vamscli tag-type list --show-tags
vamscli tag list --tag-type priority

For repeatable setup, define the structure in JSON files and apply them in batch:

vamscli tag-type create --json-input tag-types.json --json-output
vamscli tag create --json-input tags.json --json-output

---

Related Pages

• Asset Commands
• Metadata Commands
• Search Commands