datacentral-cli 1.0.0

Command-line interface for the DataCentral REST API

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:

python -m pip install .

Editable install for development:

python -m pip install -e .[dev]

After installation, verify the CLI:

dc --version
dc --help

Quick Start

# 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.

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:

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

Or via environment variable:

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

# 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 [e-mail]

# Tenants
dc tenants list
dc tenants create --tenancy-name acme --name "ACME" --admin-email [e-mail]

# 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 and the scripts under examples.

Output Modes

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

dc users list --json
dc audit list --json

Development and Validation

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

When build and twine are installed:

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

Release Guidance

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