Skip to main content

Getting Started with VamsCLI

VamsCLI is a Python command-line interface for interacting with the Visual Asset Management System (VAMS) deployed on AWS. It provides full access to the VAMS API for managing databases, assets, files, metadata, workflows, and user permissions from your terminal.

Use VamsCLI when you need to automate asset management workflows, integrate VAMS into CI/CD pipelines, perform bulk operations across large asset libraries, or script repetitive tasks that would be tedious through the web interface.

System Requirements​

RequirementVersion
Python3.13 or later
pipLatest recommended
Operating SystemWindows, macOS, or Linux
TerminalUTF-8 capable (Windows Terminal, VS Code terminal)
Windows Terminal Encoding

VamsCLI writes UTF-8 output regardless of the system code page, so no environment variable is needed. Windows Terminal and VS Code's integrated terminal display its status indicators as intended; a legacy Command Prompt may draw one as a box without affecting the command.

Quick Install​

  1. Clone or download the VAMS repository.
  2. Navigate to the CLI directory and install in development mode:
cd tools/VamsCLI
pip install -e .
  1. Verify the installation:
vamscli --version

You should see output similar to:

VamsCLI version <current-version>

First-Time Setup​

Before using VamsCLI, you must configure it to connect to your VAMS deployment. The setup command fetches the Amplify configuration from your VAMS instance and stores the API Gateway URL, Amazon Cognito User Pool details, and AWS Region automatically.

vamscli setup https://your-vams-url.example.com

The setup command accepts any HTTP or HTTPS URL that points to your VAMS deployment, including Amazon CloudFront distributions, Application Load Balancers (ALB), Amazon API Gateway endpoints, or custom domains. When you point it directly at an Amazon API Gateway execute-api endpoint, pass the bare endpoint URL — VamsCLI appends the REST API stage path (/api) automatically.

Multiple Environments

Use the --profile flag to configure separate profiles for different environments:

vamscli --profile production setup https://prod-vams.example.com
vamscli --profile staging setup https://staging-vams.example.com

Authentication​

After setup, authenticate with your VAMS instance. VamsCLI supports two authentication methods.

Amazon Cognito Authentication​

If your VAMS deployment uses Amazon Cognito for identity management and your user exists natively in the user pool:

vamscli auth login -u your.email@example.com

You will be prompted for your password. VamsCLI handles multi-factor authentication (MFA) challenges and forced password changes automatically through interactive prompts. To complete a forced change non-interactively (for example, in JSON mode), pass --new-password.

To save credentials for automatic re-authentication when tokens expire:

vamscli auth login -u your.email@example.com --save-credentials

Amazon Cognito access tokens are refreshed automatically using the stored refresh token when they expire during a command. You can also change or reset a password from the CLI:

# Change your password (you know the current one)
vamscli auth change-password -u your.email@example.com

# Reset a forgotten password using an emailed verification code
vamscli auth forgot-password -u your.email@example.com

See Setup and Authentication Commands for the full authentication command reference.

Token Override Authentication​

If your VAMS deployment uses an external OAuth identity provider (IdP), use the token override mechanism:

vamscli auth set-override -u your.email@example.com --token "eyJhbGciOiJ..."

You can specify an expiration time for the override token using Unix timestamps, ISO 8601 format, or relative seconds:

vamscli auth set-override -u user@example.com --token "token..." --expires-at "+3600"
vamscli auth set-override -u user@example.com --token "token..." --expires-at "2025-12-31T23:59:59Z"
Override Token Limitations

Override tokens do not support automatic refresh. When an override token expires, you must set a new one manually.

API Key Authentication​

If you have a VAMS API key (created through the web UI or API), you can use it directly without a password login. Store the key as an override token, naming the user ID the key was created for:

vamscli auth set-override -u api-key-user@example.com --token "your-api-key-value"

The override persists in the profile and is used by every subsequent command until it is replaced by another auth set-override or auth login, or removed with vamscli auth clear-override.

API keys impersonate the user ID they were created with and inherit that user's roles. See API Key Management for details on creating and managing API keys.

Verify Authentication​

Check your current authentication status at any time:

vamscli auth status

This displays your user ID, token type, expiration time, and enabled feature switches.

Global Options​

Every VamsCLI command supports the following global options:

OptionDescription
--profile <name>Use a named profile instead of the default profile
--verboseEnable verbose output with detailed error information, API request/response logging, and timing
--versionDisplay the VamsCLI version
--helpDisplay help for any command or subcommand

The --profile option must appear before the command name:

vamscli --profile production assets list -d my-database

Quick Example​

The following example demonstrates a typical workflow: listing databases, listing assets within a database, and uploading a file to an asset.

# List all databases
vamscli database list

# List assets in a specific database
vamscli assets list -d my-database

# Get details for a specific asset
vamscli assets get my-asset-id -d my-database

# Upload a file to an asset
vamscli file upload model.gltf -d my-database -a my-asset-id

# List files in an asset
vamscli file list -d my-database -a my-asset-id

Next Steps​