Skip to main content

Quick Start

Prerequisites:
  • The CLI uses Python. Make sure you have installed a version of python >= 3.8.
  • You must have an active account with a valid license on Platform
  • You must have at least the Data Engineer role

Local Installation​

pip install qalita

Or use the Docker image.

Windows (PowerShell)

After installation, if the qalita command is not recognized, you can always run the CLI via the Python module:

python -m qalita --help

To use qalita directly without prefixing with python -m, ensure that the Scripts folder of your Python environment is in the user PATH:

  • Python installed for the user (Microsoft Store or python.org): Usually add C:\Users\<your_user>\AppData\Local\Programs\Python\Python<version>\Scripts and C:\Users\<your_user>\AppData\Local\Programs\Python\Python<version>.
  • Virtual environment (venv): Add C:\path\to\venv\Scripts. Update PATH in PowerShell (current session):
$env:Path += ";C:\Users\<your_user>\AppData\Local\Programs\Python\Python312;C:\Users\<your_user>\AppData\Local\Programs\Python\Python312\Scripts"

Make it permanent (PowerShell profile):

if (!(Test-Path -Path $PROFILE)) { New-Item -ItemType File -Path $PROFILE -Force | Out-Null }
Add-Content -Path $PROFILE -Value '$env:Path += ";C:\Users\<your_user>\AppData\Local\Programs\Python\Python312;C:\Users\<your_user>\AppData\Local\Programs\Python\Python312\Scripts"'

Replace <your_user> and Python312 with your paths/versions. After updating the PATH, open a new terminal and run:

qalita --help

Usage​

To verify the installation and get detailed help:

qalita --help
Usage: qalita [OPTIONS] COMMAND [ARGS]...
  QALITA Command Line Interface

Quick Commands (Copy-Paste)​

  • Login agent (requires QALITA_AGENT_NAME, QALITA_AGENT_MODE, QALITA_AGENT_ENDPOINT, QALITA_AGENT_TOKEN)

You can find them by [copy/pasting] your platform Modal :

export QALITA_AGENT_NAME=agent-1
export QALITA_AGENT_MODE=worker
export QALITA_AGENT_ENDPOINT=http://localhost:3080
export QALITA_AGENT_TOKEN=xxxxxxxx
qalita agent login
  • Run a job (job mode) on an existing source and pack
QALITA_AGENT_MODE=job ; qalita agent run -s source_id -p pack_id
  • With explicit versions:
QALITA_AGENT_MODE=job qalita agent run -s <source_id> -sv <source_version> -p <pack_id> -pv <pack_version>
  • Start the agent in worker mode (infinite loop)
QALITA_AGENT_MODE=worker qalita agent run
  • List sources and packs
qalita source list
qalita pack list
  • Publish local sources (with or without validation)
qalita source push
# or
qalita source push --skip-validate

Configuration​

The CLI communicates with the QALITA platform API. Several levels of configuration exist depending on your needs:

Minimal Configuration​

  • QALITA_AGENT_NAME=agent_name The agent name allows you to identify it in the interface; no specific format is required.

  • QALITA_AGENT_MODE=job/worker Available modes:

    • Job: In job mode, qalita agent run immediately starts a process in the local context.
    • Worker: In worker mode, qalita agent run waits for orders from the backend before executing processes (similar to a scheduler).
Note: The qalita agent run command requires additional configuration to work properly, otherwise it will display errors.

Connected Configuration​

  • QALITA_AGENT_ENDPOINT=backend_api_url Example: http://localhost:3080 The API URL allows the agent to communicate with the platform and enables:

    • Pack listing
    • Job execution
    • Source publishing
    • Pack publishing

  • QALITA_AGENT_TOKEN=api_token The token is provided during the quickstart in the web application. It is associated with your user and role.

Create a .env File and Export Environment Values​

You can create a .env file and export its values to your environment.

.env-local

QALITA_AGENT_NAME=`agent_name`
QALITA_AGENT_MODE=`job/worker`
QALITA_AGENT_ENDPOINT=https://api.company.com
QALITA_AGENT_TOKEN=`api_token`
QALITA_PACK_NAME=`pack_name`

Then export the file values to your environment:

set -a; source .env-local; set +a

OS-Specific Commands (Environment Variables)​

Set environment variables according to your OS:

export QALITA_AGENT_NAME=agent_name
export QALITA_AGENT_MODE=job
export QALITA_AGENT_ENDPOINT=http://localhost:3080
export QALITA_AGENT_TOKEN=your_token_here
export QALITA_PACK_NAME=pack_name