Skip to content

Installing Qualytics CLI

Goal

Take a brand-new machine from zero to "ready to run any Qualytics CLI command." Install the CLI, authenticate, verify the setup with doctor, and run the first command. This is the first thing every new user does and the first thing every CS engineer should be able to walk a customer through.

Permissions

Setup itself doesn't require any specific role. The token you authenticate with is what gates everything afterwards.

Layer Minimum Notes
User role Member The token's role determines what you can do once authenticated. Manager or Admin is needed for system-level operations (creating connections, managing tags, etc.).
Team permission None for setup Permissions kick in when you start touching individual resources.

Prerequisites

  • Python 3.10+ installed and on $PATH. Run python3 --version to confirm.
  • A Qualytics instance URL (for example https://your-org.qualytics.io).
  • A way to authenticate: either browser login, or a token from Settings → Tokens in the web app.

On a server or in CI, use a service token

Service tokens are non-expiring credentials tied to a service account, with no UI prompts. Generate one from Settings → Service Token. See Service Token.

CLI workflow

graph LR
    Inst[Install CLI] --> Auth[Authenticate]
    Auth --> Doc[qualytics doctor]
    Doc --> Verify[List datastores]
    Verify --> Ready((Ready))

1. Install

# Recommended: uv (fast, virtualenv-friendly)
uv pip install qualytics-cli

# Or pip
pip install qualytics-cli

2. Authenticate

Browser login (interactive, easiest for a workstation):

qualytics auth login --url https://your-org.qualytics.io

Token-based (for headless or CI):

qualytics auth init \
    --url https://your-org.qualytics.io \
    --token "$QUALYTICS_TOKEN"

3. Verify

qualytics doctor

Sample passing output:

  ✓ CLI version      Qualytics CLI v1.0.0
  ✓ Python version   3.12.0
  ✓ Configuration    ~/.qualytics/config.yaml
  ✓ Auth token       Token present
  ✓ Token expiry     Expires 2026-08-15
  ✓ API connectivity https://your-org.qualytics.io: OK
  ✓ SSL certificate  Valid
  7 passed, 0 failed

4. First real command

qualytics datastores list

If you see your datastores, you're done.

Behind the scenes

CLI step Method Path Notes
auth login (browser flow) GET /oauth/authorize then /oauth/token Opens a local callback HTTP server to receive the OAuth code.
auth init (no API call) — Writes ~/.qualytics/config.yaml directly.
doctor (connectivity check) HEAD / Confirms the URL is reachable and the SSL chain is valid.
datastores list GET /api/datastores First real authenticated call.

Python equivalent

The CLI's auth wrapper is convenient but the underlying token is just a Bearer header. To call the API directly:

import os
import httpx

BASE_URL = os.environ["QUALYTICS_URL"].rstrip("/")
TOKEN    = os.environ["QUALYTICS_TOKEN"]

with httpx.Client(headers={"Authorization": f"Bearer {TOKEN}"}, timeout=30.0) as client:
    r = client.get(f"{BASE_URL}/api/datastores")
    r.raise_for_status()
    for ds in r.json():
        print(f"{ds['id']:>4}  {ds['name']}")

Variations and advanced usage

Multiple instances on one machine

The CLI uses one config file at ~/.qualytics/config.yaml. To switch between dev and prod, set environment variables that override the file:

# Dev
export QUALYTICS_URL=https://dev.qualytics.io
export QUALYTICS_TOKEN=$DEV_TOKEN
qualytics datastores list

# Prod
export QUALYTICS_URL=https://prod.qualytics.io
export QUALYTICS_TOKEN=$PROD_TOKEN
qualytics datastores list

Self-signed certificates (rare; usually internal deployments)

qualytics auth init --url https://internal.qualytics.local --token "$TOKEN" --no-verify-ssl

Only disable SSL verification in trusted internal environments

Disabling SSL verification means your connection is no longer authenticated. Don't do this against production-grade public deployments.

Cleaner CI logs

export CI=true                # also auto-detected in most CI providers
export QUALYTICS_NO_BANNER=1  # suppresses the startup banner explicitly

Troubleshooting

Symptom Likely cause Fix
qualytics: command not found after install Install path not on $PATH Try uv pip install qualytics-cli (handles the path) or check python -m site --user-base.
Browser login times out The callback port is blocked Use qualytics auth init --token instead.
doctor reports Token expired The JWT has expired Run qualytics auth login again, or rotate to a fresh service token.
doctor reports API connectivity failure URL typo, VPN required, or instance is down Verify the URL by opening it in a browser; check VPN status.
doctor reports SSL certificate invalid Self-signed cert or expired cert Re-init with --no-verify-ssl (only in trusted networks) or fix the cert.