Metadata-Version: 2.4
Name: dataverse-explorer
Version: 1.0.1
Summary: Python CLI for querying Microsoft Dataverse API with SQL-like syntax
Author-email: Kinnaird McQuade <kmcquade@beyondtrust.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/kmcquade/dataverse-explorer
Project-URL: Repository, https://github.com/kmcquade/dataverse-explorer
Project-URL: Issues, https://github.com/kmcquade/dataverse-explorer/issues
Keywords: dataverse,microsoft,power-platform,dynamics,crm,cli,odata,sql
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Database
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: msal>=1.20.0
Requires-Dist: requests>=2.28.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: click>=8.1.0
Requires-Dist: urllib3>=2.0.0
Requires-Dist: Jinja2>=3.1.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"

# Dataverse Explorer

Python CLI for querying the Dataverse API and exploring datasets. Give Cursor or your AI IDE the abiltity to run read/list queries via terminal rather than browsing the data via the slow web interface.

## Features

✅ **Auto-Discovery**: Automatically detects tenant ID and Dataverse URL from Azure/PAC CLI
✅ **SQL Queries**: Write familiar SQL syntax - automatically translated to OData
✅ **OAuth Device Code Flow**: Secure authentication with automatic token caching
✅ **Multiple Output Formats**: Table, JSON, or CSV output
✅ **CloudFlare WARP Compatible**: SSL verification disabled by default
✅ **Interactive Graph Visualization**: Cytoscape.js-powered HTML reports

## Prerequisites

- Python 3.11+
- [Power Platform CLI](https://learn.microsoft.com/en-us/power-platform/developer/howto/install-cli-net-tool?tabs=macos). 
  - It's easier if you install .NET via the installer [here](https://dotnet.microsoft.com/en-us/download/dotnet/10.0).
  - Then you can run `dotnet tool install --global Microsoft.PowerApps.CLI.Tool` to install the Power Platform CLI.
- Azure CLI (`az` command - you can install with `brew install azure-cli` on MacOS)
- Login to Azure CLI with `az login`

## Cheat sheet

Setup:

```bash
make setup-env
source venv/bin/activate

./main.py --help
# This will open up a web browser for authentication and save your configuration in .env
./main.py configure
``` 

### Listing Tables

```bash
# This will list the tables you have access to.
./main.py list-tables
# filter by tables matching 'account'
./main.py list-tables --filter account
```

### Querying Data

* Run a SQL query against a specific table:

```bash
# Clean output (smart filtering of columns to reduce noise)
./main.py query "SELECT * FROM connectionreferences LIMIT 10"

# Further reduce noise by specifying the exact column
./main.py query "SELECT name FROM account" --quiet

# Show all columns including metadata
./main.py query "SELECT * FROM connectionreferences LIMIT 10" --all-columns

# Output as JSON
./main.py query "SELECT * FROM account" --format json | jq

# Output as JSON and pipe into jq
./main.py query "SELECT * FROM account LIMIT 5" --json | jq '.value[].name'

# CSV for spreadsheets
./main.py query "SELECT name FROM account" --format csv > output.csv
```

### Dumping and Visualizing Data

```bash
# This will dump all data from the dataverse for offline analysis and graph visualization
./main.py dump-dataverse

# This will visualize the dumped dataverse data as a graph, explorable via Cytoscape.
./main.py visualize-graph --input dumped_dataverse.json --output graph.html
```

