Asset Commands
Manage assets, asset versions, asset links, and asset exports within VAMS databases. Assets are the primary containers for files, metadata, and version history.
assets create
Create a new asset in VAMS. Asset IDs are automatically generated by the system.
vamscli assets create [OPTIONS]
| Option | Type | Required | Description |
|---|---|---|---|
-d, --database-id | TEXT | Yes | Database ID where the asset will be created |
--name | TEXT | Conditional | Asset name (required unless using --json-input) |
--description | TEXT | Conditional | Asset description (required unless using --json-input) |
--distributable / --no-distributable | Flag | Conditional | Whether the asset is distributable |
--tags | TEXT | No | Asset tags (can be used multiple times) |
--bucket-key | TEXT | No | Existing Amazon S3 bucket key to use |
--json-input | TEXT | No | JSON input file path or JSON string |
--json-output | Flag | No | Output raw JSON response |
vamscli assets create -d my-database --name "My Asset" --description "Asset description"
vamscli assets create -d my-database --name "Tagged Asset" --description "With tags" --tags tag1 --tags tag2 --distributable
vamscli assets create -d my-database --json-input '{"assetName":"test","description":"desc","isDistributable":true}'
assets list
List assets in a database or all assets across databases.
vamscli assets list [OPTIONS]
| Option | Type | Required | Description |
|---|---|---|---|
-d, --database-id | TEXT | No | Database ID (optional for all assets) |
--show-archived | Flag | No | Include archived assets |
--page-size | INTEGER | No | Number of items per page |
--max-items | INTEGER | No | Maximum total items (only with --auto-paginate) |
--starting-token | TEXT | No | Token for manual pagination |
--auto-paginate | Flag | No | Automatically fetch all items |
--json-output | Flag | No | Output raw JSON response |
vamscli assets list -d my-database
vamscli assets list -d my-database --auto-paginate --json-output
vamscli assets list -d my-database --show-archived
assets get
Get details for a specific asset.
vamscli assets get <ASSET_ID> [OPTIONS]
| Option | Type | Required | Description |
|---|---|---|---|
ASSET_ID | TEXT | Yes | Asset ID to retrieve (positional) |
-d, --database-id | TEXT | Yes | Database ID containing the asset |
--show-archived | Flag | No | Include archived assets |
--json-output | Flag | No | Output raw JSON response |
assets update
Update an existing asset.
vamscli assets update <ASSET_ID> [OPTIONS]
| Option | Type | Required | Description |
|---|---|---|---|
ASSET_ID | TEXT | Yes | Asset ID to update (positional) |
-d, --database-id | TEXT | Yes | Database ID containing the asset |
--name | TEXT | No | New asset name |
--description | TEXT | No | New asset description |
--distributable / --no-distributable | Flag | No | Update distributable flag |
--tags | TEXT | No | New tags (replaces existing) |
--json-input | TEXT | No | JSON input file path or JSON string |
--json-output | Flag | No | Output raw JSON response |
assets archive
Archive an asset (soft delete). Archived assets can be recovered.
vamscli assets archive <ASSET_ID> [OPTIONS]
| Option | Type | Required | Description |
|---|---|---|---|
ASSET_ID | TEXT | Yes | Asset ID to archive (positional) |
-d, --database | TEXT | Yes | Database ID containing the asset |
--reason | TEXT | No | Reason for archiving |
--json-input | TEXT | No | JSON input file path or JSON string |
--json-output | Flag | No | Output raw JSON response |
assets unarchive
Unarchive an asset (restore from soft delete). Restores the asset record so it appears in normal listings again. The asset's files remain archived by default; pass --unarchive-files to also restore the files that the asset archive operation archived.
vamscli assets unarchive <ASSET_ID> [OPTIONS]
| Option | Type | Required | Description |
|---|---|---|---|
ASSET_ID | TEXT | Yes | Asset ID to unarchive (positional) |
-d, --database | TEXT | Yes | Database ID containing the asset |
--reason | TEXT | No | Reason for unarchiving |
--unarchive-files | Flag | No | Also restore the files archived by the asset archive operation |
--json-input | TEXT | No | JSON input file path or JSON string |
--json-output | Flag | No | Output raw JSON response |
vamscli assets unarchive my-asset -d my-database
vamscli assets unarchive my-asset -d my-database --unarchive-files
vamscli assets unarchive my-asset -d my-database --reason "Restoring for review"
Only archived assets can be unarchived. Use vamscli assets get <ASSET_ID> -d <DB> --show-archived to confirm an asset's archived state.
--unarchive-files restores only the files that were archived by the asset archive itself (tracked by assetArchive provenance in the file version history). Files archived individually beforehand always stay archived — restore those with vamscli file unarchive. Assets archived before provenance tracking have no restorable file set, so no files are restored for them.
assets delete
Permanently delete an asset and all associated data.
vamscli assets delete <ASSET_ID> [OPTIONS]
| Option | Type | Required | Description |
|---|---|---|---|
ASSET_ID | TEXT | Yes | Asset ID to delete (positional) |
-d, --database | TEXT | Yes | Database ID containing the asset |
--confirm | Flag | Yes | Confirm permanent deletion |
--reason | TEXT | No | Reason for deletion |
--json-output | Flag | No | Output raw JSON response |
This action permanently removes the asset record, all files and versions from Amazon S3, all links and relationships, comments, version history, metadata, and SNS topics.
assets download
Download files from an asset with advanced options for version selection, tree traversal, and shareable links.
vamscli assets download [LOCAL_PATH] [OPTIONS]
| Option | Type | Required | Description |
|---|---|---|---|
LOCAL_PATH | PATH | Conditional | Local directory for downloads (optional with --shareable-links-only) |
-d, --database | TEXT | Yes | Database ID |
-a, --asset | TEXT | Yes | Asset ID |
--file-key | TEXT | No | Specific file key to download (defaults to / when --recursive is used) |
--recursive | Flag | No | Download all files from folder tree (defaults --file-key to / if not specified) |
--flatten-download-tree | Flag | No | Ignore folder structure, download flat |
--asset-preview | Flag | No | Download only the asset preview file |
--file-previews | Flag | No | Additionally download file preview files |
--asset-version-id | TEXT | No | Download files from a specific asset version snapshot (whole set) |
--asset-version-alias | TEXT | No | Download files from a specific asset version by alias (whole set) |
--version-id | TEXT | No | S3 version ID for a single --file-key (per-file version) |
--asset-link-children-tree-depth | INTEGER | No | Traverse child link tree to specified depth |
--shareable-links-only | Flag | No | Return presigned URLs without downloading |
--parallel-downloads | INTEGER | No | Max parallel downloads (default: 5) |
--retry-attempts | INTEGER | No | Retry attempts per file (default: 3) |
--timeout | INTEGER | No | Download timeout per file in seconds (default: 300) |
--hide-progress | Flag | No | Hide download progress display |
--json-output | Flag | No | Output raw JSON response |
--asset-version-id and --asset-version-alias are mutually exclusive and pin the whole download (folder, tree, or entire asset) to that asset version snapshot — the file list itself reflects the files as they existed in that version. --version-id selects a specific S3 version of a single --file-key and cannot be combined with the asset-version flags. With no version option, the latest version of each file is downloaded.
Multi-file downloads and --shareable-links-only generate presigned URLs through the bulk download API (up to 1,500 files per request), so large assets prepare in a handful of API calls rather than one per file. Files that cannot be signed (missing or archived) are reported and skipped.
vamscli assets download /local/path -d my-db -a my-asset
vamscli assets download /local/path -d my-db -a my-asset --recursive
vamscli assets download /local/path -d my-db -a my-asset --file-key "/model.gltf"
vamscli assets download /local/path -d my-db -a my-asset --file-key "/models/" --recursive
vamscli assets download /local/path -d my-db -a my-asset --asset-version-id 2
vamscli assets download /local/path -d my-db -a my-asset --asset-version-alias "stable-release"
vamscli assets download -d my-db -a my-asset --shareable-links-only
vamscli assets download /local/path -d my-db -a my-asset --asset-link-children-tree-depth 2
The command exits non-zero when any file did not arrive, so a partial transfer is distinguishable from a complete one. The report still goes to stdout: overall_success gives the outcome, and each entry in failed_downloads names a file in relative_key with the reason in error. A file the service declines to issue a download URL for is counted as a failure like any other — an asset that is not distributable, for example, lists its files but permits none of them to be fetched, and that reads as failed_downloads entries rather than an empty success. When nothing at all could be prepared, the error message names the reason.
assets export
Export comprehensive asset data including metadata, files, relationships, and optional presigned download URLs. Designed for mass exports and downstream data consumption.
vamscli assets export [OPTIONS]
| Option | Type | Required | Description |
|---|---|---|---|
-d, --database-id | TEXT | Yes | Database ID containing the asset |
-a, --asset-id | TEXT | Yes | Root asset ID to export |
--auto-paginate / --no-auto-paginate | Flag | No | Enable/disable automatic pagination (default: enabled) |
--max-assets | INTEGER | No | Maximum assets per page (1-1000, default: 100) |
--max-files | INTEGER | No | Maximum files per page (1-10000, default: 2000) |
--starting-token | TEXT | No | Pagination token from previous response |
--no-fetch-relationships | Flag | No | Skip fetching relationships (single asset only) |
--fetch-entire-subtrees | Flag | No | Fetch complete descendant tree (all levels) |
--include-parent-relationships | Flag | No | Include parent relationships |
--generate-presigned-urls | Flag | No | Generate presigned download URLs for files |
--include-folder-files | Flag | No | Include folder files in export |
--include-only-primary-type-files | Flag | No | Include only files with primaryType set |
--include-archived-files | Flag | No | Include archived files |
--file-extensions | TEXT | No | Filter by extension (repeatable, e.g., .gltf .bin) |
--no-file-metadata | Flag | No | Exclude file metadata |
--no-asset-link-metadata | Flag | No | Exclude asset link metadata |
--no-asset-metadata | Flag | No | Exclude asset metadata |
--download-files | Flag | No | Download files to a local directory |
--local-path | PATH | No | Local directory (required with --download-files) |
--organize-by-asset | Flag | No | Save files flat within a per-asset subdirectory |
--flatten-downloads | Flag | No | Save all files flat in --local-path |
--parallel-downloads | INTEGER | No | Max parallel downloads (default: 5) |
--download-timeout | INTEGER | No | Download timeout per file in seconds (default: 300) |
--hide-download-progress | Flag | No | Hide download progress display |
--json-input | TEXT | No | JSON input file path or JSON string with all options |
--json-output | Flag | No | Output raw JSON response |
vamscli assets export -d my-database -a my-asset
vamscli assets export -d my-database -a my-asset --fetch-entire-subtrees --json-output > export.json
vamscli assets export -d my-database -a my-asset --file-extensions .gltf --file-extensions .bin --generate-presigned-urls
vamscli assets export -d my-database -a my-asset --no-fetch-relationships
vamscli assets export -d my-database -a my-asset --download-files --local-path ./export --organize-by-asset
--download-files exports the asset data and retrieves the files in a single command, using the same parallel download manager as assets download. It requires --local-path, and it enables --generate-presigned-urls automatically.
The two organization flags require --download-files, are mutually exclusive, and control the local layout:
- Default — files are written to
LOCAL_PATH/ASSET_ID/with their asset folder structure preserved. --organize-by-asset— files are written flat intoLOCAL_PATH/ASSET_ID/.--flatten-downloads— files from every exported asset are written flat intoLOCAL_PATH/. :::
--max-files bounds the files one page returns across all of its assets, so a page can end before --max-assets assets. An asset holding more files than the budget is returned over successive pages, each resuming its file list where the last one stopped.
--auto-paginate (the default) follows those pages and merges each asset's files into a single entry, so the combined output holds one record per asset with its complete file list. With --no-auto-paginate, an entry whose file list is partial reports files_truncated; pass the returned token to --starting-token to retrieve the rest of that asset before the export moves on to its siblings.
assets history
List the lifecycle history records for an asset. Records are returned newest first and cover create, edit, archive, unarchive, and permanent delete operations, each with the acting user and a snapshot of the asset fields after the operation. Records backfilled by the deployment data migration are marked as migrated.
vamscli assets history [OPTIONS]
| Option | Type | Required | Description |
|---|---|---|---|
-d, --database | TEXT | Yes | Database ID containing the asset |
-a, --asset | TEXT | Yes | Asset ID to get history for |
--page-size | INTEGER | No | Number of items per page |
--max-items | INTEGER | No | Maximum total items (only with --auto-paginate) |
--starting-token | TEXT | No | Token for manual pagination |
--auto-paginate | Flag | No | Automatically fetch all items |
--json-input | TEXT | No | JSON input file path or JSON string |
--json-output | Flag | No | Output raw JSON response |
vamscli assets history -d my-database -a my-asset
vamscli assets history -d my-database -a my-asset --auto-paginate --json-output
vamscli assets history -d my-database -a my-asset --page-size 50
History records persist across permanent deletion. If an asset is permanently deleted and later recreated with the same asset ID, the prior history (including the permanentDelete record) remains visible for that ID. History for a permanently deleted asset ID that has not been recreated returns a 404.
asset-version create
Create a new version snapshot of an asset's current state.
vamscli asset-version create [OPTIONS]
| Option | Type | Required | Description |
|---|---|---|---|
-d, --database | TEXT | Yes | Database ID |
-a, --asset | TEXT | Yes | Asset ID |
--comment | TEXT | Yes | Comment for the new version |
--alias | TEXT | No | Version alias (e.g., RC1, GA, Beta; max 64 characters) |
--use-latest-files | Flag | No | Use latest files in Amazon S3 (default: true) |
--files | TEXT | No | JSON string or file path with specific files to version |
--json-output | Flag | No | Output raw JSON response |
vamscli asset-version create -d my-db -a my-asset --comment "Release candidate" --alias "RC1"
asset-version list
List all versions for an asset. Archived versions are hidden by default.
vamscli asset-version list [OPTIONS]
| Option | Type | Required | Description |
|---|---|---|---|
-d, --database | TEXT | Yes | Database ID |
-a, --asset | TEXT | Yes | Asset ID |
--show-archived | Flag | No | Include archived versions |
| Pagination options | No | --page-size (maximum 1000), --max-items, --starting-token, --auto-paginate | |
--json-output | Flag | No | Output raw JSON response |
asset-version get
Get details for a specific version, including versioned metadata and attributes.
vamscli asset-version get -d <DB> -a <ASSET> -v <VERSION> [--json-output]
asset-version update
Update the comment or alias for an existing version.
vamscli asset-version update -d <DB> -a <ASSET> -v <VERSION> [--comment TEXT] [--alias TEXT]
At least one of --comment or --alias must be provided. Pass an empty string to --alias to clear it.
asset-version archive / unarchive
Archive or restore a version. The current (latest) version cannot be archived.
vamscli asset-version archive -d my-db -a my-asset -v 2
vamscli asset-version unarchive -d my-db -a my-asset -v 2
asset-version revert
Revert an asset to a previous version, optionally including metadata.
vamscli asset-version revert [OPTIONS]
| Option | Type | Required | Description |
|---|---|---|---|
-d, --database | TEXT | Yes | Database ID |
-a, --asset | TEXT | Yes | Asset ID |
-v, --version | TEXT | Yes | Version ID to revert to |
--comment | TEXT | No | Comment for the new version created by revert |
--revert-metadata / --no-revert-metadata | Flag | No | Revert metadata and attributes (default: false) |
--json-output | Flag | No | Output raw JSON response |
vamscli asset-version revert -d my-db -a my-asset -v 1 --comment "Reverting to stable"
vamscli asset-version revert -d my-db -a my-asset -v 1 --revert-metadata
asset-links create
Create a relationship between two assets.
vamscli asset-links create [OPTIONS]
| Option | Type | Required | Description |
|---|---|---|---|
--from-asset-id | TEXT | Yes | Source asset ID |
--from-database-id | TEXT | Yes | Source database ID |
--to-asset-id | TEXT | Yes | Target asset ID |
--to-database-id | TEXT | Yes | Target database ID |
--relationship-type | TEXT | Yes | related or parentChild |
--alias-id | TEXT | No | Alias ID for multiple parent-child links (parentChild only, max 128 chars) |
--tags | TEXT | No | Tags (repeatable) |
--json-input | TEXT | No | JSON input |
--json-output | Flag | No | Output raw JSON |
The --alias-id option enables multiple parent-child relationships between the same pair of assets. Each alias must be unique for a given child asset.
asset-links list / get / update / delete
vamscli asset-links list -d my-db --asset-id my-asset [--tree-view]
vamscli asset-links get --asset-link-id <UUID>
vamscli asset-links update --asset-link-id <UUID> --tags new-tag
vamscli asset-links delete --asset-link-id <UUID>
A --tree-view listing walks at most 100 levels and 10,000 assets. When it reaches either ceiling, the output says the tree is incomplete (treeTruncated in --json-output) — list the links of an asset further down the tree for the rest of it. Links whose asset could not be read are reported separately from unauthorized ones, under Unresolved Assets (unresolvedCounts in --json-output), and usually clear on a retry.