Getting Started with vastpy-cli

vastpy-cli is a command-line interface for the VAST Data REST API, installed as part of the vastpy Python package. It provides a simple, schema-agnostic way to interact with any VAST API endpoint using standard HTTP verbs (get, post, patch, delete). This guide covers installation, authentication, and practical examples to get you operational quickly. For the full SDK reference, see the vastpy GitHub repository.

Prerequisites

• Python 3.6 or later installed on a host with network access to the VAST VMS
• Network connectivity to the VMS IP address on port 443 (HTTPS)
• VMS Manager account with appropriate permissions
• jq installed (recommended for formatting JSON output)

1. Installing vastpy

Install or upgrade the package via pip:

pip install --upgrade vastpy

For systems using pip3 explicitly:

pip3 install --upgrade vastpy

Verify the installation:

vastpy-cli --help

Output:

usage: vastpy-cli [-h] [--user USER] [--password PASSWORD] [--address ADDRESS]
                  [--version VERSION] [--json] ...

(optional): To install jq for JSON output processing:

sudo apt-get install -y jq     # Ubuntu/Debian
sudo yum install -y jq         # Rocky/RHEL
brew install jq                # macOS

2. Configuring Authentication

vastpy-cli reads credentials from environment variables or from flags passed directly on the command line. Environment variables are the recommended approach for interactive use.

Setting Up Environment Variables

export VMS_USER=admin
 export VMS_PASSWORD=your_password   # leading space prevents storing in shell history
export VMS_ADDRESS=vast-vms-address  # hostname or IP of your VMS

Note: The leading space before export VMS_PASSWORD is intentional. Most shells (bash, zsh) skip history logging for commands that begin with a space, which avoids storing credentials in ~/.bash_history.

Per-Command Credentials

If you prefer not to use environment variables, pass credentials with each command:

vastpy-cli --user=admin --password=your_password --address=vast-vms-address get clusters

Token-Based Authentication (VAST 5.3+)

On VAST 5.3 and later, you can authenticate using an API token:

vastpy-cli --token=<your-api-token> --address=vast-vms-address get clusters

Generate a token programmatically using the Python SDK:

from vastpy import VASTClient

client = VASTClient(user='admin', password='your_password', address='vast-vms-address')
token = client.apitokens.post(owner='admin')
print(token)

3. Command Syntax

The general structure for all vastpy-cli commands is:

vastpy-cli [OPTIONS] METHOD RESOURCE [KEY=VALUE ...]
vastpy-cli [OPTIONS] METHOD RESOURCE/ID [KEY=VALUE ...]
vastpy-cli [OPTIONS] METHOD RESOURCE/ID/ACTION [KEY=VALUE ...]

The --json flag requests JSON-formatted output, which is required when piping to jq.

4. Example: Verify Setup and Explore the Cluster

Before running more complex operations, verify connectivity and authentication by listing basic cluster information.

# List all clusters
vastpy-cli --json get clusters | jq '.[] | {id: .id, name: .name, version: .sw_version}'

Output:

{
  "id": 1,
  "name": "prod-cluster-01",
  "version": "5.5.0"
}

List current NFS and S3 views:

vastpy-cli --json get views | jq '.[] | {id: .id, name: .name, path: .path, protocols: .protocols}'

List available view policies:

vastpy-cli get viewpolicies fields=id,name

These read-only commands are a safe way to confirm your credentials are working and to orient yourself to the cluster configuration before making changes.

5. Example: Creating and Listing Snapshots

Snapshots capture the state of a directory at a point in time. This example creates a snapshot of a directory and then lists all snapshots to confirm.

Create a Snapshot

vastpy-cli post snapshots \
  path=/pkg/andypern \
  name=project-alpha-snap-$(date +%Y%m%d)

Output:

property               |value
-----------------------+------------------------------------------------------------+
id                     |267191
guid                   |90aaa697-8dd4-46be-91e1-90926997e707
name                   |project-alpha-snap-20260416
url                    |https://10.143.11.201/api/latest/snapshots/267191
title                  |project-alpha-snap-20260416(/pkg/andypern/)
path                   |/pkg/andypern/
expiration_time        |3001-01-19T07:59:58Z
cluster                |selab-var-201
state                  |SUCCEED
locked                 |False
policy                 |None
policy_id              |None
created                |2026-04-16T16:42:12.024040Z
type                   |local
protection_policy_id   |None
eta_sec                |30760442262.88283
indestructible         |False
aggr_phys_estimation   |0
unique_phys_estimation |0
tenant_id              |1
tenant_name            |default
access_path            |/.vast_all_snapshots/1000557532_project-alpha-snap-20260416
clone_id               |1000557532
subsystem_related      |False

Troubleshooting

Issue: vastpy-cli: command not found

1. Confirm pip install vastpy completed without errors.
2. Check that Python's script directory is in your $PATH (e.g., ~/.local/bin for user installs).
3. Try running python3 -m vastpy as a fallback.

Issue: Authentication fails with 401 or connection refused

1. Verify VMS_ADDRESS is reachable on port 443: curl -sk https://<VMS_ADDRESS>/api/clusters.
2. Confirm the account has VMS Manager permissions.
3. Check that VMS_USER and VMS_PASSWORD are set in the current shell session (not just in a script).

Issue: Key=value format errors
4. Parameters must have no spaces around =. Use name=myview, not name = myview.
5. For complex values (lists, nested objects), wrap in single quotes: protocols='["NFS","SMB"]'.

Command Reference Summary

Common options:

Links and References

Official Documentation

• vastpy on PyPI
• vastpy GitHub Repository

Related Knowledge Base Articles

• Capacity Analysis with vastpy-cli
• Creating a Directory Clone and Exposing It as a View with CLI

Community and Support

• VAST Support Portal

Conclusion

With vastpy-cli installed and authentication configured via environment variables, you have direct CLI access to every VAST API endpoint. The examples above cover the most common starting points: verifying connectivity, managing snapshots, and querying the Catalog for capacity analysis. From here, explore any endpoint shown in vastpy-cli get --help using the same METHOD RESOURCE KEY=VALUE pattern.

Citations