pvw-cli 1.8.5
Microsoft Purview CLI with comprehensive automation capabilities
Requires Python: >=3.8
Keywords: azure, purview, cli, data, catalog, governance, automation, pvw

# PURVIEW CLI v1.8.5 - Microsoft Purview Automation & Data Governance

[![Version](https://img.shields.io/badge/version-1.8.3-blue.svg)](https://github.com/Keayoub/pvw-cli/releases/tag/v1.8.5)
[![API Coverage](https://img.shields.io/badge/UC%20API%20Coverage-96%25-brightgreen.svg)](https://github.com/Keayoub/pvw-cli)
[![Lineage](https://img.shields.io/badge/Lineage-Enhanced-green.svg)](https://github.com/Keayoub/pvw-cli)
[![Status](https://img.shields.io/badge/status-stable-success.svg)](https://github.com/Keayoub/pvw-cli)

> **LATEST UPDATE v1.8.5 (February 6, 2026):**
>
> **CSV Term Import - Multi-Value Separator Standardization & Enhanced Dry-Run**
>
> - **[FIXED]** CSV separator conflicts - all multi-value fields now use semicolon (`;`) exclusively
> - **[IMPROVED]** Dry-run output with visual indicators showing post-processing operations
> - **[ADDED]** Comprehensive CSV column reference documentation
> - **[ADDED]** Enhanced validation for separator usage
> - **[UPDATED]** Sample CSVs with proper semicolon separators
> - **[BREAKING]** Multi-value fields must use semicolon, not comma
>
> **[Full Release Notes v1.8.5](releases/v1.8.5.md)** | **[CSV Column Reference](samples/csv/UC_TERMS_CSV_COLUMNS_REFERENCE.md)** | **[CSV Examples](samples/csv/)**
>
> **Previous Update v1.8.1 (January 28, 2026):**
>
> **Unified Catalog APIs - Analytics & Visualization**
>
> - List Hierarchy Terms with interactive tree visualization
> - Get Term Facets for statistics and filters
> - Get CDE, Data Product, and Objective Facets
> - List Related Entities for relationship exploration
> - UC API Coverage increased to **96%** (+15%)
>
> **[Archive](releases/)**

---

## What is PVW CLI?

**PVW CLI v1.8.5** is a modern, full-featured command-line interface and Python library for Microsoft Purview. It enables automation and management of *all major Purview APIs* with **96% Unified Catalog API coverage** (46 of 48 operations).

### Key Capabilities

**Unified Catalog (UC) Management - 96% Complete** ⭐ *NEW*
- **[NEW]** Glossary hierarchy visualization with interactive tree views
- **[NEW]** Facets & analytics for terms, CDEs, data products, and objectives
- **[NEW]** Complete relationship exploration for terms
- Complete governance domains, glossary terms, data products, OKRs, CDEs
- Relationships API - Link data products/CDEs/terms to entities and columns
- Query APIs - Advanced OData filtering with multi-criteria search
- Policy Management - Complete CRUD for governance and RBAC policies
- Custom Metadata & Attributes - Extensible business metadata and attributes

**Data Operations**
- Entity management (create, update, bulk, import/export)
- Lineage operations with interactive creation and CSV import
- Advanced search and discovery with fixed suggest/autocomplete
- Business metadata with proper scope configuration

**Collections Management - 100% Spec Compliant**
- Full collection CRUD operations with proper API conformance
- Hierarchy and tree operations for collection navigation
- Permission management for collection access control
- Analytics for collection usage and asset tracking

**Automation & Scripting**
- Bulk Operations - Import/export from CSV/JSON with dry-run support
- Scriptable Output - Multiple formats (table, json, jsonc) for PowerShell/bash
- 80+ usage examples and 15+ comprehensive guides
- PowerShell integration with ConvertFrom-Json support

**Legacy API Support**
- Account management with full API compatibility
- Data product management (legacy operations)
- Classification, label, and status management

The CLI is designed for data engineers, stewards, architects, and platform teams to automate, scale, and enhance their Microsoft Purview experience.

### NEW: MCP Server for AI Assistants

**[NEW]** Model Context Protocol (MCP) server enables LLM-powered data governance workflows! 

- Natural language interface to Purview catalog
- 20+ tools for AI assistants (Claude, Cline, etc.)
- Automate complex multi-step operations
- See `mcp/README.md` for setup instructions

---

## Release Information

For detailed information about previous releases, see the **[Full Release Archive](releases/)**.

**Latest Release:** [v1.8.1](releases/v1.8.1.md) (January 28, 2026)  
**Previous Release:** [v1.6.2](releases/v1.6.2.md) (January 27, 2026)

---

## 📊 API Coverage Summary

### Unified Catalog (UC) - 96% Complete ⭐

| Category | Coverage | Count | Status |
|----------|----------|-------|--------|
| **Glossary Terms** | 100% | 9/9 | ✅ Complete |
| **Domains** | 100% | 5/5 | ✅ Complete |
| **Data Products** | 100% | 8/8 | ✅ Complete |
| **Critical Data Elements (CDE)** | 100% | 8/8 | ✅ Complete |
| **Objectives (OKRs)** | 100% | 6/6 | ✅ Complete |
| **Key Results** | 100% | 5/5 | ✅ Complete |
| **Policies** | 100% | 4/4 | ✅ Complete |
| **Facets & Analytics** | 100% | 4/4 | ✅ Complete |
| **Relationships** | 100% | 3/3 | ✅ Complete |
| **Hierarchy** | 100% | 1/1 | ✅ Complete |
| **TOTAL UC** | **96%** | **46/48** | 🎯 **Production Ready** |

### 🎯 New in v1.8.1 - Six Advanced UC APIs

1. **List Hierarchy Terms (NEW)**
   ```bash
   # Interactive tree view of glossary hierarchy
   pvw uc term hierarchy --output tree
   
   # Filter by domain with max depth control
   pvw uc term hierarchy --domain-id <domain-guid> --max-depth 3 --output table
   ```

2. **Get Term Facets (NEW)**
   ```bash
   # Statistics and filters for glossary terms
   pvw uc term facets --output table
   
   # JSON export for automation
   pvw uc term facets --output json
   ```

3. **Get CDE Facets (NEW)**
   ```bash
   # Compliance dashboards (GDPR, HIPAA, SOC2)
   pvw uc cde facets --domain-id <domain-guid> --output table
   
   # See color-coded compliance summary
   pvw uc cde facets --facet-fields "criticality,compliance_status"
   ```

4. **Get Data Product Facets (NEW)**
   ```bash
   # Analytics for data product portfolios
   pvw uc dataproduct facets --output table
   
   # Filter by domain
   pvw uc dataproduct facets --domain-id <domain-guid> --output json
   ```

5. **Get Objective Facets (NEW)**
   ```bash
   # OKR dashboards with health metrics
   pvw uc objective facets --output table
   
   # JSON export for dashboards
   pvw uc objective facets --output json
   ```

6. **List Related Entities (NEW)**
   ```bash
   # Complete relationship exploration for terms
   pvw uc term relationships --term-id <term-guid> --output table
   
   # Filter by relationship type (Synonym, Related, Parent)
   pvw uc term relationships --term-id <term-guid> --relationship-type "Synonym"
   ```
---

## Getting Started

Follow this short flow to get PVW CLI installed and running quickly.

1. Install (from PyPI):

  ```bash
  pip install pvw-cli
  ```

  For the bleeding edge or development:

  ```bash
  pip install git+https://github.com/Keayoub/Purview_cli.git
  # or for editable development
  git clone https://github.com/Keayoub/Purview_cli.git
  cd Purview_cli
  pip install -r requirements.txt
  pip install -e .
  ```

2. Set required environment variables (examples for cmd, PowerShell, and pwsh)

  Windows cmd (example):

  ```cmd
  set PURVIEW_ACCOUNT_NAME=your-purview-account
  set PURVIEW_ACCOUNT_ID=your-purview-account-id-guid
  set PURVIEW_RESOURCE_GROUP=your-resource-group-name
  set AZURE_REGION=  # optional
  ```

  PowerShell (Windows PowerShell):

  ```powershell
  $env:PURVIEW_ACCOUNT_NAME = "your-purview-account"
  $env:PURVIEW_ACCOUNT_ID = "your-purview-account-id-guid"
  $env:PURVIEW_RESOURCE_GROUP = "your-resource-group-name"
  $env:AZURE_REGION = ""  # optional
  ```

  pwsh (PowerShell Core - cross-platform, recommended):

  ```pwsh
  $env:PURVIEW_ACCOUNT_NAME = 'your-purview-account'
  $env:PURVIEW_ACCOUNT_ID = 'your-purview-account-id-guid'
  $env:PURVIEW_RESOURCE_GROUP = 'your-resource-group-name'
  $env:AZURE_REGION = ''  # optional
  ```

3. Authenticate

- Run `az login` (recommended), or
- Provide Service Principal credentials via environment variables.

**Important for Legacy Tenants:**

Some Azure environments use the legacy Purview service principal (`https://purview.azure.net`) instead of the current one (`https://purview.azure.com`). If you encounter authentication errors like:

```
AADSTS500011: The resource principal named https://purview.azure.com was not found in the tenant
```

You need to detect and set the correct authentication scope:

**Step 1: Detect your tenant's Purview service principal**

```powershell
# Check which service principal your tenant uses
az ad sp show --id "73c2949e-da2d-457a-9607-fcc665198967" --query "servicePrincipalNames" -o json
```

Look for one of these values:
- `https://purview.azure.com` or `https://purview.azure.com/` → Use `.com` (default)
- `https://purview.azure.net` or `https://purview.azure.net/` → Use `.net` (legacy)

**Step 2: Set the authentication scope (if using legacy .net)**

If your tenant uses the legacy service principal, set this environment variable:

```powershell
# PowerShell
$env:PURVIEW_AUTH_SCOPE = "https://purview.azure.net/.default"

# Or add to your profile for persistence
Add-Content $PROFILE "`n`$env:PURVIEW_AUTH_SCOPE = 'https://purview.azure.net/.default'"
```

```bash
# Bash/Linux
export PURVIEW_AUTH_SCOPE="https://purview.azure.net/.default"

# Or add to ~/.bashrc for persistence
echo 'export PURVIEW_AUTH_SCOPE="https://purview.azure.net/.default"' >> ~/.bashrc
```

```cmd
# Windows CMD
set PURVIEW_AUTH_SCOPE=https://purview.azure.net/.default
```

**Note:** Most modern Azure tenants use `https://purview.azure.com` (default), but some legacy or special environments (test, government clouds) may still use `https://purview.azure.net`. Always verify using the command above if you encounter authentication issues.

4. Try a few commands:

  ```bash
  # List governance domains
  pvw uc domain list

  # Search
  pvw search query --keywords="customer" --limit=5

  # Get help
  pvw --help
  pvw uc --help
  ```

For more advanced usage, see the documentation in `doc/` or the project docs: <https://pvw-cli.readthedocs.io/>

---

## Quick Start Examples

### Collections Management (v1.6.2+)

```bash
# Create a new collection
pvw collections create \
  --name "Data Engineering" \
  --friendly-name "Data Engineering Team" \
  --description "Collection for DE team assets"

# List collection hierarchy
pvw collections read-hierarchy --collection-name "Data Engineering"

# Update collection
pvw collections update \
  --name "Data Engineering" \
  --friendly-name "Data Engineering (Updated)"

# Manage collection permissions
pvw collections read-permissions --collection-name "Data Engineering"
```

### Lineage Management

```bash
# Create column-level lineage
pvw lineage create-column \
  --process-name "ETL_Sales_Transform" \
  --source-table-guid "9ebbd583-4987-4d1b-b4f5-d8f6f6f60000" \
  --target-table-guids "c88126ba-5fb5-4d33-bbe2-5ff6f6f60000" \
  --column-mapping "ProductID:ProductID,Name:Name"

# Import lineage from CSV
pvw lineage import samples/csv/lineage_with_columns.csv

# List column lineages
pvw lineage list-column --format table
```

### Governance & Relationships

```bash
# Link data product to entity
pvw uc dataproduct link-entity \
  --id "dp-sales-2024" \
  --entity-id "4fae348b-e960-42f7-834c-38f6f6f60000" \
  --type-name "azure_sql_table"

# Link CDE to specific column
pvw uc cde link-entity \
  --id "cde-customer-email" \
  --entity-id "ea3412c3-7387-4bc1-9923-11f6f6f60000" \
  --column-qualified-name "mssql://server/db/schema/table#EmailAddress"

# Query terms by domain
pvw uc term query --domain-ids "finance,sales" --status Approved --top 50
```

### Policy & Metadata

```bash
# List all policies
pvw uc policy list

# Create policy
pvw uc policy create --payload-file policy-rbac.json

# Import business metadata
pvw uc custom-metadata import --file business_concept.csv

# Add metadata to entity
pvw uc custom-metadata add \
  --guid "4fae348b-e960-42f7-834c-38f6f6f60000" \
  --name "BusinessConcept" \
  --attributes '{"Department":"Sales"}'
```

---

## Installation

You can install PVW CLI in two ways:

1. **From PyPI (recommended for most users):**

   ```bash
   pip install pvw-cli
   ```

2. **Directly from the GitHub repository (for latest/dev version):**

   ```bash
   pip install git+https://github.com/Keayoub/Purview_cli.git
   ```

Or for development (editable install):

```bash
git clone https://github.com/Keayoub/Purview_cli.git
cd Purview_cli
pip install -r requirements.txt
pip install -e .
```

---

## Requirements

- Python 3.8+
- Azure CLI (`az login`) or Service Principal credentials
- Microsoft Purview account

---

## Getting Started

1. **Install**

   ```bash
   pip install pvw-cli
   ```

2. **Set Required Environment Variables**

   ```bash
   # Required for Purview API access
   set PURVIEW_ACCOUNT_NAME=your-purview-account
   set PURVIEW_ACCOUNT_ID=your-purview-account-id-guid
   set PURVIEW_RESOURCE_GROUP=your-resource-group-name
   
   # Optional
   set AZURE_REGION=  # (optional, e.g. 'china', 'usgov')
   ```

3. **Authenticate**

   - Azure CLI: `az login`

   - Or set Service Principal credentials as environment variables

4. **Run a Command**

   ```bash
   pvw search query --keywords="customer" --limit=5
   ```

5. **See All Commands**

   ```bash
   pvw --help
   ```

---

## Authentication

PVW CLI supports multiple authentication methods for connecting to Microsoft Purview, powered by Azure Identity's `DefaultAzureCredential`. This allows you to use the CLI securely in local development, CI/CD, and production environments.

### 1. Azure CLI Authentication (Recommended for Interactive Use)

- Run `az login` to authenticate interactively with your Azure account.
- The CLI will automatically use your Azure CLI credentials.

### 2. Service Principal Authentication (Recommended for Automation/CI/CD)

Set the following environment variables before running any PVW CLI command:

- `AZURE_CLIENT_ID` (your Azure AD app registration/client ID)
- `AZURE_TENANT_ID` (your Azure AD tenant ID)
- `AZURE_CLIENT_SECRET` (your client secret)

**Example (Windows):**

```cmd
set AZURE_CLIENT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
set AZURE_TENANT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
set AZURE_CLIENT_SECRET=your-client-secret
```

**Example (Linux/macOS):**

```bash
export AZURE_CLIENT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
export AZURE_TENANT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
export AZURE_CLIENT_SECRET=your-client-secret
```

### 3. Managed Identity (for Azure VMs, App Services, etc.)

If running in Azure with a managed identity, no extra configuration is needed. The CLI will use the managed identity automatically.

### 4. Visual Studio/VS Code Authentication

If you are signed in to Azure in Visual Studio or VS Code, `DefaultAzureCredential` can use those credentials as a fallback.

---

**Note:**

- The CLI will try all supported authentication methods in order. The first one that works will be used.
- For most automation and CI/CD scenarios, service principal authentication is recommended.
- For local development, Azure CLI authentication is easiest.

For more details, see the [Azure Identity documentation](https://learn.microsoft.com/en-us/python/api/overview/azure/identity-readme?view=azure-python).

---

## Output Formats & Scripting Integration

PVW CLI supports multiple output formats to fit different use cases - from human-readable tables to machine-parseable JSON.

### Output Format Options

All `list` commands now support the `--output` parameter with three formats:

1. **`table`** (default) - Rich formatted table with colors for human viewing
2. **`json`** - Plain JSON for scripting with PowerShell, bash, jq, etc.
3. **`jsonc`** - Colored JSON with syntax highlighting for viewing

### PowerShell Integration

The `--output json` format produces plain JSON that works perfectly with PowerShell's `ConvertFrom-Json`:

```powershell
# Get all terms as PowerShell objects
$domainId = "59ae27b5-40bc-4c90-abfe-fe1a0638fe3a"
$terms = py -m purviewcli uc term list --domain-id $domainId --output json | ConvertFrom-Json

# Access properties
Write-Host "Found $($terms.Count) terms"
foreach ($term in $terms) {
    Write-Host "  • $($term.name) - $($term.status)"
}

# Filter and export
$draftTerms = $terms | Where-Object { $_.status -eq "Draft" }
$draftTerms | Export-Csv -Path "draft_terms.csv" -NoTypeInformation

# Group by status
$terms | Group-Object status | Format-Table Count, Name
```

### Bash/Linux Integration

Use `jq` for JSON processing in bash:

```bash
# Get domain ID
DOMAIN_ID="59ae27b5-40bc-4c90-abfe-fe1a0638fe3a"

# Get term names only
pvw uc term list --domain-id $DOMAIN_ID --output json | jq -r '.[] | .name'

# Count terms
pvw uc term list --domain-id $DOMAIN_ID --output json | jq 'length'

# Filter by status
pvw uc term list --domain-id $DOMAIN_ID --output json | jq '.[] | select(.status == "Draft")'

# Group by status
pvw uc term list --domain-id $DOMAIN_ID --output json | jq 'group_by(.status) | map({status: .[0].status, count: length})'

# Save to file
pvw uc term list --domain-id $DOMAIN_ID --output json > terms.json
```

### Examples by Command

```bash
# Domains
pvw uc domain list --output json | jq '.[] | .name'

# Terms  
pvw uc term list --domain-id "abc-123" --output json
pvw uc term list --domain-id "abc-123" --output table   # Default
pvw uc term list --domain-id "abc-123" --output jsonc   # Colored for viewing

# Data Products
pvw uc dataproduct list --domain-id "abc-123" --output json
```

### Migration from Old --json Flag

**Old (deprecated):**

```bash
pvw uc term list --domain-id "abc-123" --json
```

**New (recommended):**

```bash
pvw uc term list --domain-id "abc-123" --output json    # Plain JSON for scripting
pvw uc term list --domain-id "abc-123" --output jsonc   # Colored JSON (old behavior)
```

---

## Required Purview Configuration

Before using PVW CLI, you need to set three essential environment variables. Here's how to find them:

### 🔍 **How to Find Your Purview Values**

#### **1. PURVIEW_ACCOUNT_NAME**

- This is your Purview account name as it appears in Azure Portal
- Example: `kaydemopurview`

#### **2. PURVIEW_ACCOUNT_ID**

- This is the GUID that identifies your Purview account for Unified Catalog APIs
- **Important: For most Purview deployments, this is your Azure Tenant ID**

- **Method 1 - Get your Tenant ID (recommended):**
  
  **Bash/Command Prompt:**

  ```bash
  az account show --query tenantId -o tsv
  ```
  
  **PowerShell:**

  ```powershell
  az account show --query tenantId -o tsv
  # Or store directly in environment variable:
  $env:PURVIEW_ACCOUNT_ID = az account show --query tenantId -o tsv
  ```

- **Method 2 - Azure CLI (extract from Atlas endpoint):**

  ```bash
  az purview account show --name YOUR_ACCOUNT_NAME --resource-group YOUR_RG --query endpoints.catalog -o tsv
  ```

  Extract the GUID from the URL (before `-api.purview-service.microsoft.com`)

- **Method 3 - Azure Portal:**
  1. Go to your Purview account in Azure Portal
  2. Navigate to Properties → Atlas endpoint URL
  3. Extract GUID from: `https://GUID-api.purview-service.microsoft.com/catalog`

#### **3. PURVIEW_RESOURCE_GROUP**

- The Azure resource group containing your Purview account
- Example: `fabric-artifacts`

### 📋 **Setting the Variables**

**Windows Command Prompt:**

```cmd
set PURVIEW_ACCOUNT_NAME=your-purview-account
set PURVIEW_ACCOUNT_ID=your-purview-account-id
set PURVIEW_RESOURCE_GROUP=your-resource-group
```

**Windows PowerShell:**

```powershell
$env:PURVIEW_ACCOUNT_NAME="your-purview-account"
$env:PURVIEW_ACCOUNT_ID="your-purview-account-id" 
$env:PURVIEW_RESOURCE_GROUP="your-resource-group"
```

**Linux/macOS:**

```bash
export PURVIEW_ACCOUNT_NAME=your-purview-account
export PURVIEW_ACCOUNT_ID=your-purview-account-id
export PURVIEW_RESOURCE_GROUP=your-resource-group
```

**Permanent (Windows Command Prompt):**

```cmd
setx PURVIEW_ACCOUNT_NAME "your-purview-account"
setx PURVIEW_ACCOUNT_ID "your-purview-account-id"
setx PURVIEW_RESOURCE_GROUP "your-resource-group"
```

**Permanent (Windows PowerShell):**

```powershell
[Environment]::SetEnvironmentVariable("PURVIEW_ACCOUNT_NAME", "your-purview-account", "User")
[Environment]::SetEnvironmentVariable("PURVIEW_ACCOUNT_ID", "your-purview-account-id", "User")
[Environment]::SetEnvironmentVariable("PURVIEW_RESOURCE_GROUP", "your-resource-group", "User")
```

### **Debug Environment Issues**

If you experience issues with environment variables between different terminals, use these debug commands:

**Command Prompt/Bash:**

```bash
# Run this to check your current environment
python -c "
import os
print('PURVIEW_ACCOUNT_NAME:', os.getenv('PURVIEW_ACCOUNT_NAME'))
print('PURVIEW_ACCOUNT_ID:', os.getenv('PURVIEW_ACCOUNT_ID'))
print('PURVIEW_RESOURCE_GROUP:', os.getenv('PURVIEW_RESOURCE_GROUP'))
"
```

**PowerShell:**

```powershell
# Check environment variables in PowerShell
python -c "
import os
print('PURVIEW_ACCOUNT_NAME:', os.getenv('PURVIEW_ACCOUNT_NAME'))
print('PURVIEW_ACCOUNT_ID:', os.getenv('PURVIEW_ACCOUNT_ID'))
print('PURVIEW_RESOURCE_GROUP:', os.getenv('PURVIEW_RESOURCE_GROUP'))
"

# Or use PowerShell native commands
Write-Host "PURVIEW_ACCOUNT_NAME: $env:PURVIEW_ACCOUNT_NAME"
Write-Host "PURVIEW_ACCOUNT_ID: $env:PURVIEW_ACCOUNT_ID" 
Write-Host "PURVIEW_RESOURCE_GROUP: $env:PURVIEW_RESOURCE_GROUP"
```

---

## Search Command (Discovery Query API)

The PVW CLI provides advanced search using the latest Microsoft Purview Discovery Query API:

- Search for assets, tables, files, and more with flexible filters
- Use autocomplete and suggestion endpoints
- Perform faceted, time-based, and entity-type-specific queries

**v1.6.2 Enhancements:**

- Collections API now 100% conformant with Microsoft Purview specification
- Improved search result caching and performance
- Enhanced error handling and diagnostics
- All search commands validated and working correctly (query, browse, suggest, find-table)

### CLI Usage Examples

#### **Multiple Output Formats**

```bash
# 1. Table Format (Default) - Quick overview
pvw search query --keywords="customer" --limit=5
# → Clean table with Name, Type, Collection, Classifications, Qualified Name

# 2. Detailed Format - Human-readable with all metadata  
pvw search query --keywords="customer" --limit=5 --detailed
# → Rich panels showing full details, timestamps, search scores

# 3. JSON Format - Complete technical details with syntax highlighting (WELL-FORMATTED)
pvw search query --keywords="customer" --limit=5 --json
# → Full JSON response with indentation, line numbers and color coding

# 4. Table with IDs - For entity operations
pvw search query --keywords="customer" --limit=5 --show-ids
# → Table format + entity GUIDs for copy/paste into update commands
```

#### **Search Operations**

```bash
# Basic search for assets with keyword 'customer'
pvw search query --keywords="customer" --limit=5

# Advanced search with classification filter
pvw search query --keywords="sales" --classification="PII" --objectType="Tables" --limit=10

# Pagination through large result sets
pvw search query --keywords="SQL" --offset=10 --limit=5

# Autocomplete suggestions for partial keyword
pvw search autocomplete --keywords="ord" --limit=3

# Get search suggestions (fuzzy matching)
pvw search suggest --keywords="prod" --limit=2

**IMPORTANT - Command Line Quoting:**
```cmd
# [OK] CORRECT - Use quotes around keywords
pvw search query --keywords="customer" --limit=5

# [OK] CORRECT - For wildcard searches, use quotes
pvw search query --keywords="*" --limit=5

# ❌ WRONG - Don't use unquoted * (shell expands to file names)
pvw search query --keywords=* --limit=5
# This causes: "Error: Got unexpected extra arguments (dist doc ...)"
```

```bash
# Faceted search with aggregation
pvw search query --keywords="finance" --facetFields="objectType,classification" --limit=5

# Browse entities by type and path
pvw search browse --entityType="Tables" --path="/root/finance" --limit=2

# Time-based search for assets created after a date
pvw search query --keywords="audit" --createdAfter="2024-01-01" --limit=1

# Entity type specific search
pvw search query --keywords="finance" --entityTypes="Files,Tables" --limit=2
```

#### **Usage Scenarios**

- **Daily browsing**: Use default table format for quick scans
- **Understanding assets**: Use `--detailed` for rich information panels  
- **Technical work**: Use `--json` for complete API data access
- **Entity operations**: Use `--show-ids` to get GUIDs for updates

### Python Usage Example

```python
from purviewcli.client._search import Search

search = Search()
args = {"--keywords": "customer", "--limit": 5}
search.searchQuery(args)
print(search.payload)  # Shows the constructed search payload
```

### Test Examples

See `tests/test_search_examples.py` for ready-to-run pytest examples covering all search scenarios:

- Basic query
- Advanced filter
- Autocomplete
- Suggest
- Faceted search
- Browse
- Time-based search
- Entity type search

---

## Unified Catalog Management (NEW)

PVW CLI now includes comprehensive **Microsoft Purview Unified Catalog (UC)** support with the new `uc` command group. This provides complete management of modern data governance features including governance domains, glossary terms, data products, objectives (OKRs), and critical data elements.

**🎯 Feature Parity**: Full compatibility with [UnifiedCatalogPy](https://github.com/olafwrieden/unifiedcatalogpy) functionality.

See [`doc/commands/unified-catalog.md`](doc/commands/unified-catalog.md) for complete documentation and examples.

### Quick UC Examples

#### **Governance Domains Management**

```bash
# List all governance domains
pvw uc domain list

# Create a new governance domain
pvw uc domain create --name "Finance" --description "Financial data governance domain"

# Get domain details
pvw uc domain get --domain-id "abc-123-def-456"

# Update domain information
pvw uc domain update --domain-id "abc-123" --description "Updated financial governance"
```

#### **Glossary Terms in UC**

```bash
# List all terms in a domain
pvw uc term list --domain-id "abc-123"
pvw uc term list --domain-id "abc-123" --output json    # Plain JSON for scripting
pvw uc term list --domain-id "abc-123" --output jsonc   # Colored JSON for viewing

# Create a single glossary term
pvw uc term create --name "Customer" --domain-id "abc-123" --description "A person or entity that purchases products"

# Get term details
pvw uc term show --term-id "term-456"

# Update term
pvw uc term update --term-id "term-456" --description "Updated description"

# Delete term
pvw uc term delete --term-id "term-456" --confirm
```

**📦 Bulk Import (NEW)**

Import multiple terms from CSV or JSON files with validation and progress tracking:

```bash
# CSV Import - Preview with dry-run
pvw uc term import-csv --csv-file "samples/csv/uc_terms_bulk_example.csv" --domain-id "abc-123" --dry-run

# CSV Import - Actual import
pvw uc term import-csv --csv-file "samples/csv/uc_terms_bulk_example.csv" --domain-id "abc-123"

# JSON Import - Preview with dry-run
pvw uc term import-json --json-file "samples/json/term/uc_terms_bulk_example.json" --dry-run

# JSON Import - Actual import (domain_id from JSON or override with flag)
pvw uc term import-json --json-file "samples/json/term/uc_terms_bulk_example.json"
pvw uc term import-json --json-file "samples/json/term/uc_terms_bulk_example.json" --domain-id "abc-123"
```

**Bulk Import Features:**

- [OK] Import from CSV or JSON files
- [OK] Dry-run mode to preview before importing
- [OK] Support for multiple owners (Entra ID Object IDs), acronyms, and resources
- [OK] Progress tracking with Rich console output
- [OK] Detailed error messages and summary reports
- [OK] Sequential POST requests (no native bulk endpoint available)

**CSV Format Example:**

```csv
name,description,status,acronym,owner_id,resource_name,resource_url
Customer Acquisition Cost,Cost to acquire new customer,Draft,CAC,<guid>,Metrics Guide,https://docs.example.com
Monthly Recurring Revenue,Predictable monthly revenue,Draft,MRR,<guid>,Finance Dashboard,https://finance.example.com
```

**JSON Format Example:**

```json
{
  "terms": [
    {
      "name": "Data Lake",
      "description": "Centralized repository for structured/unstructured data",
      "domain_id": "your-domain-id-here",
      "status": "Draft",
      "acronyms": ["DL"],
      "owner_ids": ["<entra-id-object-id-guid>"],
      "resources": [{"name": "Architecture Guide", "url": "https://example.com"}]
    }
  ]
}
```

**Important Notes:**

- ⚠️ **Owner IDs must be Entra ID Object IDs (GUIDs)**, not email addresses
- ⚠️ **Terms cannot be "Published" in unpublished domains** - use "Draft" status
- [OK] Sample files available: `samples/csv/uc_terms_bulk_example.csv`, `samples/json/term/uc_terms_bulk_example.json`
- 📖 Complete documentation: [`doc/commands/unified-catalog/term-bulk-import.md`](doc/commands/unified-catalog/term-bulk-import.md)

**🗑️ Bulk Delete (NEW)**

Delete all terms in a domain using PowerShell or Python scripts:

```powershell
# PowerShell - Delete all terms with confirmation
.\scripts\delete-all-uc-terms.ps1 -DomainId "abc-123"

# PowerShell - Delete without confirmation
.\scripts\delete-all-uc-terms.ps1 -DomainId "abc-123" -Force
```

```bash
# Python - Delete all terms with confirmation
python scripts/delete_all_uc_terms_v2.py --domain-id "abc-123"

# Python - Delete without confirmation
python scripts/delete_all_uc_terms_v2.py --domain-id "abc-123" --force
```

**Bulk Delete Features:**

- [OK] Interactive confirmation prompts (type "DELETE" to confirm)
- [OK] Beautiful progress display with colors
- [OK] Success/failure tracking per term
- [OK] Detailed summary reports
- [OK] Rate limiting (200ms delay between deletes)
- [OK] Graceful error handling and Ctrl+C support

#### **Data Products Management**

```bash
# List all data products in a domain
pvw uc dataproduct list --domain-id "abc-123"

# Create a comprehensive data product
pvw uc dataproduct create \
  --name "Customer Analytics Dashboard" \
  --domain-id "abc-123" \
  --description "360-degree customer analytics with behavioral insights" \
  --type Analytical \
  --status Draft

# Get detailed data product information
pvw uc dataproduct show --product-id "prod-789"

# Update data product (partial updates supported - only specify fields to change)
pvw uc dataproduct update \
  --product-id "prod-789" \
  --status Published \
  --description "Updated comprehensive customer analytics" \
  --endorsed

# Update multiple fields at once
pvw uc dataproduct update \
  --product-id "prod-789" \
  --status Published \
  --update-frequency Monthly \
  --endorsed

# Delete a data product (with confirmation)
pvw uc dataproduct delete --product-id "prod-789"

# Delete without confirmation prompt
pvw uc dataproduct delete --product-id "prod-789" --yes
```

#### **Objectives & Key Results (OKRs)**

```bash
# List objectives for a domain
pvw uc objective list --domain-id "abc-123"

# Create measurable objectives
pvw uc objective create \
  --definition "Improve data quality score by 25% within Q4" \
  --domain-id "abc-123" \
  --target-value "95" \
  --measurement-unit "percentage"

# Track objective progress
pvw uc objective update \
  --objective-id "obj-456" \
  --domain-id "abc-123" \
  --current-value "87" \
  --status "in-progress"
```

#### **Critical Data Elements (CDEs)**

```bash
# List critical data elements
pvw uc cde list --domain-id "abc-123"

# Define critical data elements with governance rules
pvw uc cde create \
  --name "Social Security Number" \
  --data-type "String" \
  --domain-id "abc-123" \
  --classification "PII" \
  --retention-period "7-years"

# Associate CDEs with data assets
pvw uc cde link \
  --cde-id "cde-789" \
  --domain-id "abc-123" \
  --asset-id "ea3412c3-7387-4bc1-9923-11f6f6f60000"
```

#### **Health Monitoring (NEW)**

Monitor governance health and get automated recommendations to improve your data governance posture.

```bash
# List all health findings and recommendations
pvw uc health query

# Filter by severity
pvw uc health query --severity High
pvw uc health query --severity Medium

# Filter by status
pvw uc health query --status NotStarted
pvw uc health query --status InProgress

# Get detailed information about a specific health action
pvw uc health show --action-id "5ea3fc78-6a77-4098-8779-ed81de6f87c9"

# Update health action status
pvw uc health update \
  --action-id "5ea3fc78-6a77-4098-8779-ed81de6f87c9" \
  --status InProgress \
  --reason "Working on assigning glossary terms to data products"

# Get health summary statistics
pvw uc health summary

# Output health findings in JSON format
pvw uc health query --json
```

**Health Finding Types:**

- Missing glossary terms on data products (High)
- Data products without OKRs (Medium)
- Missing data quality scores (Medium)
- Classification gaps on data assets (Medium)
- Description quality issues (Medium)
- Business domains without critical data entities (Medium)

#### **Workflow Management (NEW)**

Manage approval workflows and business process automation in Purview.

```bash
# List all workflows
pvw workflow list

# Get workflow details
pvw workflow get --workflow-id "workflow-123"

# Create a new workflow (requires JSON definition)
pvw workflow create --workflow-id "approval-flow-1" --payload-file workflow-definition.json

# Execute a workflow
pvw workflow execute --workflow-id "workflow-123"

# List workflow executions
pvw workflow executions --workflow-id "workflow-123"

# View specific execution details
pvw workflow execution-details --workflow-id "workflow-123" --execution-id "exec-456"

# Update workflow configuration
pvw workflow update --workflow-id "workflow-123" --payload-file updated-workflow.json

# Delete a workflow
pvw workflow delete --workflow-id "workflow-123"

# Output workflows in JSON format
pvw workflow list --json
```

**Workflow Use Cases:**

- Data access request approvals
- Glossary term certification workflows
- Data product publishing approvals
- Classification review processes

#### **Integrated Workflow Example**

```bash
# 1. Discover assets to govern
pvw search query --keywords="customer" --detailed

# 2. Create governance domain for discovered assets
pvw uc domain create --name "Customer Data" --description "Customer information governance"

# 3. Define governance terms
pvw uc term create --name "Customer PII" --domain-id "new-domain-id" --definition "Personal customer information"

# 4. Create data product from discovered assets
pvw uc dataproduct create --name "Customer Master Data" --domain-id "new-domain-id"

# 5. Set governance objectives
pvw uc objective create --definition "Ensure 100% PII classification compliance" --domain-id "new-domain-id"
```

---

## Entity Management & Updates

PVW CLI provides comprehensive entity management capabilities for updating Purview assets like descriptions, classifications, and custom attributes.

### **Entity Update Examples**

#### **Update Asset Descriptions**

```bash
# Update table description using GUID
pvw entity update-attribute \
  --guid "ece43ce5-ac45-4e50-a4d0-365a64299efc" \
  --attribute "description" \
  --value "Updated customer data warehouse table with enhanced analytics"

# Update dataset description using qualified name
pvw entity update-attribute \
  --qualifiedName "https://app.powerbi.com/groups/abc-123/datasets/def-456" \
  --attribute "description" \
  --value "Power BI dataset for customer analytics dashboard"
```

#### **Bulk Entity Operations**

```bash
# Read entity details before updating
pvw entity read-by-attribute \
  --guid "ea3412c3-7387-4bc1-9923-11f6f6f60000" \
  --attribute "description,classifications,customAttributes"

# Update multiple attributes at once
pvw entity update-bulk \
  --input-file entities_to_update.json \
  --output-file update_results.json
```

#### **Column-Level Updates**

```bash
# Update specific column descriptions in a table
pvw entity update-attribute \
  --guid "column-guid-123" \
  --attribute "description" \
  --value "Customer unique identifier - Primary Key"

# Add classifications to sensitive columns
pvw entity add-classification \
  --guid "column-guid-456" \
  --classification "MICROSOFT.PERSONAL.EMAIL"
```

### **Discovery to Update Workflow**

```bash
# 1. Find assets that need updates
pvw search query --keywords="customer table" --show-ids --limit=10

# 2. Get detailed information about a specific asset
pvw entity read-by-attribute --guid "FOUND_GUID" --attribute "description,classifications"

# 3. Update the asset description
pvw entity update-attribute \
  --guid "FOUND_GUID" \
  --attribute "description" \
  --value "Updated description based on business requirements"

# 4. Verify the update
pvw search query --keywords="FOUND_GUID" --detailed
```

---

## Lineage CSV Import & Management

PVW CLI provides powerful lineage management capabilities including CSV-based bulk import for automating data lineage creation.

### **Lineage CSV Import**

Import lineage relationships from CSV files to automate the creation of data flow documentation in Microsoft Purview.

#### **CSV Format**

The CSV file must contain the following columns:

**Required columns:**

- `source_entity_guid` - GUID of the source entity
- `target_entity_guid` - GUID of the target entity

**Optional columns:**

- `relationship_type` - Type of relationship (default: "Process")
- `process_name` - Name of the transformation process
- `description` - Description of the transformation
- `confidence_score` - Confidence score (0-1)
- `owner` - Process owner
- `metadata` - Additional JSON metadata

**Example CSV:**

```csv
source_entity_guid,target_entity_guid,relationship_type,process_name,description,confidence_score,owner,metadata
dcfc99ed-c74d-49aa-bd0b-72f6f6f60000,1db9c650-acfb-4914-8bc5-1cf6f6f60000,Process,Transform_Product_Data,Transform product data for analytics,0.95,data-engineering,"{""tool"": ""Azure Data Factory""}"
```

#### **Lineage Commands**

```bash
# Validate CSV format before import (no API calls)
pvw lineage validate lineage_data.csv

# Import lineage relationships from CSV
pvw lineage import lineage_data.csv

# Generate sample CSV file with examples
pvw lineage sample output.csv --num-samples 10 --template detailed

# View available CSV templates
pvw lineage templates
```

#### **Available Templates**

- **`basic`** - Minimal columns (source, target, process name)
- **`detailed`** - All columns including metadata and confidence scores
- **`qualified_names`** - Use qualified names instead of GUIDs

#### **Workflow Example**

```bash
# 1. Find entity GUIDs using search
pvw search find-table --name "Product" --schema "dbo" --id-only

# 2. Create CSV file with lineage relationships
# (use the GUIDs from step 1)

# 3. Validate CSV format
pvw lineage validate my_lineage.csv
# Output: SUCCESS: Lineage validation passed (5 rows, 8 columns)

# 4. Import to Purview
pvw lineage import my_lineage.csv
# Output: SUCCESS: Lineage import completed successfully
```

#### **Advanced Features**

- **GUID Validation**: Automatic validation of GUID format with helpful error messages
- **Process Entity Creation**: Creates intermediate "Process" entities to link source→target relationships
- **Metadata Support**: Add custom JSON metadata to each lineage relationship
- **Dry-Run Validation**: Validate CSV format locally before making API calls

**For detailed documentation, see:** [`doc/guides/lineage-csv-import.md`](doc/guides/lineage-csv-import.md)

---

## Data Product Management (Legacy)

PVW CLI also includes the original `data-product` command group for backward compatibility with traditional data product lifecycle management.

See [`doc/commands/data-product.md`](doc/commands/data-product.md) for full documentation and examples.

### Example