--- title: "Getting Started with vastpy-cli" slug: "getting-started-with-vastpy-cli" description: "Vastpy-cli simplifies VAST Data API interactions via command line, covering installation, authentication, and practical examples for efficient usage." updated: 2026-10-23T18:20:32Z published: 2026-10-23T18:22:41Z canonical: "docs.vastdata.com/getting-started-with-vastpy-cli" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.vastdata.com/llms.txt > Use this file to discover all available pages before exploring further. # 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](https://github.com/vast-data/vastpy). ## 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= --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 ...] ``` | Component | Description | | --- | --- | | `OPTIONS` | `--user`, `--password`, `--address`, `--json`, etc. | | `METHOD` | `get`, `post`, `patch`, `delete` | | `RESOURCE` | API endpoint name (e.g., `clusters`, `views`, `snapshots`) | | `ID` | Numeric ID of a specific resource instance | | `KEY=VALUE` | Request parameters; no spaces around `=` | 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 | Method | Syntax | Description | | --- | --- | --- | | `get` | `vastpy-cli get RESOURCE` | List all objects of a resource type | | `get` | `vastpy-cli get RESOURCE/ID` | Get a single object by ID | | `get` | `vastpy-cli get RESOURCE fields=f1,f2` | List with specific fields only | | `post` | `vastpy-cli post RESOURCE key=val ...` | Create a new object | | `post` | `vastpy-cli post RESOURCE -i file.json` | Create from JSON file | | `patch` | `vastpy-cli patch RESOURCE/ID key=val` | Update an existing object | | `delete` | `vastpy-cli delete RESOURCE/ID` | Delete an object | Common options: | Option | Description | | --- | --- | | `--json` | Output as JSON (required for `jq` piping) | | `--user` | VMS username (overrides `VMS_USER`) | | `--password` | VMS password (overrides `VMS_PASSWORD`) | | `--address` | VMS hostname or IP (overrides `VMS_ADDRESS`) | | `--version` | Target a specific API version | | `-i FILE` | Read request body from a JSON file | ## Links and References ### Official Documentation - [vastpy on PyPI](https://pypi.org/project/vastpy/) - [vastpy GitHub Repository](https://github.com/vast-data/vastpy) ### Related Knowledge Base Articles - [Capacity Analysis with vastpy-cli](https://kb.vastdata.com/docs/capacity-analysis-with-vastpy-cli) - [Creating a Directory Clone and Exposing It as a View with CLI](https://kb.vastdata.com/docs/creating-a-directory-clone-and-exposing-it-as-a-view-with-cli) ### Community and Support - [VAST Support Portal](https://support.vastdata.com/) ## 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 | Source | Summary | | --- | --- | | https://github.com/vast-data/vastpy | Official vastpy README; used for installation requirements, authentication methods, CLI syntax overview, and API mapping pattern | | https://kb.vastdata.com/docs/capacity-analysis-with-vastpy-cli | Published KB article; used for authentication environment variable pattern, Catalog query examples, `jq` aggregation patterns, and cold-data filter examples | | https://kb.vastdata.com/docs/creating-a-directory-clone-and-exposing-it-as-a-view-with-cli | Published KB article; used for snapshot create/list/delete workflow and `key=value` format note | | https://kb.vastdata.com/docs/syncengine-vast-cluster-setup-guide | Published KB article; used for token auth note, view policy listing, and per-command credential syntax | | `auto-docs/catalog/catalog-reporting-vastpy.md` | Internal draft doc; used for Catalog query endpoint name (`bigcatalogconfig/query_data`), field and filter syntax, and jq output patterns | ---