Metadata-Version: 2.4
Name: datacentral-cli
Version: 1.0.0
Summary: Command-line interface for the DataCentral REST API
Author: DataCentral CLI maintainers
License-Expression: MIT
Keywords: datacentral,cli,powerbi,administration,automation
Classifier: Development Status :: 5 - Production/Stable
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click<9,>=8.1
Requires-Dist: requests<3,>=2.31
Provides-Extra: dev
Requires-Dist: build>=1.2.2; extra == "dev"
Requires-Dist: pytest<9,>=8.0; extra == "dev"
Requires-Dist: twine<7,>=6.1; extra == "dev"
Dynamic: license-file

# DataCentral CLI

`datacentral-cli` provides the `dc` command for scripting and administering a DataCentral environment from the terminal. It covers common authentication, user, tenant, role, Power BI, audit, cache, language, settings, and navigation workflows through the platform REST API.

## Highlights

- Installable as a standard Python package with a working `dc` entry point.
- Human-readable tables by default, strict JSON output with `--json` for scripting.
- Persistent config file plus environment-variable overrides for CI/CD and automation.
- Retries and clearer API error handling for transient failures.
- Cross-platform usage on Windows, macOS, and Linux.

## Installation

From a local checkout:

```bash
python -m pip install .
```

Editable install for development:

```bash
python -m pip install -e .[dev]
```

After installation, verify the CLI:

```bash
dc --version
dc --help
```

## Quick Start

```bash
# Configure the base URL once
dc config set url https://your-datacentral-host

# Log in and persist the access token
dc auth login --username admin

# Validate the local setup
dc doctor

# Start working
dc users list
dc tenants list
dc pbi reports list
```

A more detailed walkthrough is in [docs/quickstart.md](docs/quickstart.md).

## Configuration

The CLI stores local settings in `~/.datacentral/config.json` by default. Override the location with `DATACENTRAL_CONFIG_DIR`.

### Supported environment overrides

| Variable | Purpose |
| --- | --- |
| `DATACENTRAL_URL` | Default base URL |
| `DATACENTRAL_TOKEN` | Access token override |
| `DATACENTRAL_TENANT_ID` | Tenant header override |
| `DATACENTRAL_TIMEOUT` | HTTP timeout in seconds |
| `DATACENTRAL_API_KEY` | API key for token-free auth |
| `DATACENTRAL_VERIFY_SSL` | `true` / `false` toggle |
| `DATACENTRAL_CONFIG_DIR` | Config storage directory |

Environment variables take precedence over values stored on disk. This is the recommended approach for CI/CD pipelines.

### API key authentication

Instead of logging in with a username and password you can authenticate using an API key. This is useful for non-interactive scripts and CI/CD pipelines:

```bash
dc config set url https://your-datacentral-host
dc config set api_key YOUR_API_KEY
dc users list
```

Or via environment variable:

```bash
export DATACENTRAL_URL=https://your-datacentral-host
export DATACENTRAL_API_KEY=YOUR_API_KEY
dc users list
```

When an API key is configured the CLI sends it as an `X-API-Key` header. If a Bearer token is also present, the token takes precedence.

## Common Commands

```bash
# Authentication
dc auth login --username admin
dc auth refresh
dc auth whoami
dc auth logout

# Users
dc users list --max 100
dc users get 42
dc users create --username jdoe --name John --surname Doe --email jdoe@example.com

# Tenants
dc tenants list
dc tenants create --tenancy-name acme --name "ACME" --admin-email admin@acme.com

# Roles
dc roles list
dc roles permissions

# Power BI
dc pbi workspaces list
dc pbi reports list
dc pbi embed token 12
```

More command recipes are collected in [docs/examples.md](docs/examples.md) and the scripts under [examples](examples).

## Output Modes

Default output is optimized for human operators. Add `--json` to emit machine-readable JSON only.

```bash
dc users list --json
dc audit list --json
```

## Development and Validation

```bash
python -m unittest discover -s tests -v
python -m compileall src tests
```

When `build` and `twine` are installed:

```bash
python -m build
python -m twine check dist/*
```

## Release Guidance

The release process for GitHub and PyPI publication is documented in [docs/releasing.md](docs/releasing.md).
