Skip to content

Getting Started

This guide shows how to install, configure, authenticate, and run your first pvw-cli commands.

Prerequisites

Before installing the CLI, make sure you have:

  • Python 3.8 or later
  • pip available in your Python environment
  • Access to a Microsoft Purview account
  • Azure credentials that can access that Purview account
  • Azure CLI installed if you want the simplest local sign-in flow

Recommended before first use:

  • Run az login for local interactive authentication
  • Confirm your Purview account name, tenant ID, and resource group
  • Use a virtual environment so CLI dependencies stay isolated

The packages declared in pyproject.toml are runtime dependencies and are installed automatically when you run pip install pvw-cli. You normally do not need to install them one by one unless you are debugging or developing the CLI itself.

1. Install

Install from PyPI:

pip install pvw-cli

Create and activate a virtual environment if you want an isolated install:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install --upgrade pip
pip install pvw-cli

Or install from source:

git clone https://github.com/Keayoub/pvw-cli.git
cd pvw-cli
pip install -r requirements.txt
pip install -e .

Runtime dependency summary

pvw-cli installs these automatically:

  • azure-identity: authentication through DefaultAzureCredential
  • azure-core: Azure SDK pipeline primitives and shared client behavior
  • click: command-line parsing and command group registration
  • rich: formatted terminal output, tables, colors, and diagnostics
  • requests: synchronous HTTP calls to Purview REST APIs
  • pandas: CSV and tabular bulk-processing workflows
  • aiohttp: async HTTP support for high-throughput or concurrent operations
  • pydantic: typed configuration and validation models
  • PyYAML: YAML parsing for config and structured metadata inputs
  • cryptography: secure auth and token/certificate support used by the auth stack

2. Sign in to Azure

For local development, the easiest option is Azure CLI authentication:

az login

3. Configure Environment Variables

Set these values before using the CLI.

PowerShell:

$env:PURVIEW_ACCOUNT_NAME = "your-purview-account"
$env:PURVIEW_ACCOUNT_ID = "your-tenant-id-guid"
$env:PURVIEW_RESOURCE_GROUP = "your-resource-group"

Bash:

export PURVIEW_ACCOUNT_NAME=your-purview-account
export PURVIEW_ACCOUNT_ID=your-tenant-id-guid
export PURVIEW_RESOURCE_GROUP=your-resource-group

To get your tenant ID:

az account show --query tenantId -o tsv

Using a .env file

For local development, store your configuration in a .env file instead of setting environment variables in every terminal session. pvw-cli automatically loads this file from the current working directory at startup.

Create .env in your project root:

PURVIEW_ACCOUNT_NAME=your-purview-account
PURVIEW_ACCOUNT_ID=your-tenant-id-guid
PURVIEW_RESOURCE_GROUP=your-resource-group

Keep .env out of source control

Your .env contains account identifiers. Add it to .gitignore:

.env is already in the default .gitignore for this project.
If you use Service Principal credentials, never store AZURE_CLIENT_SECRET in a committed file. Use Azure Key Vault or CI/CD secrets instead.

4. Verify the CLI

Check the available commands:

pvw --help

Check one command group:

pvw search --help

5. Run Your First Commands

Read account details:

pvw account getAccount

Search the catalog:

pvw search query --keywords "customer"

List glossary terms:

pvw glossary readTerms

If your primary goal is modern governance in Microsoft Purview, continue with the dedicated Unified Catalog page.

6. Troubleshooting Authentication

If you see a legacy tenant resource principal issue, set:

export PURVIEW_AUTH_SCOPE=https://purview.azure.net/.default

If you need more help, see: