CLI – qualinkctl

qualinkctl is the command-line interface for qualink. It lets you run YAML-driven data-quality validations directly from the terminal — no Python script required.

Installation

qualinkctl is installed automatically when you install the qualink package:

uv add qualink

Or using pip:

pip install qualink

Verify the installation:

qualinkctl --help

Quick Start

Given a YAML validation config (e.g. checks.yaml):

suite:
  name: "User Data Quality"

data_sources:
  - name: users_source
    format: csv
    path: "users.csv"
    table_name: users

checks:
  - name: "Completeness"
    level: error
    rules:
      - is_complete: user_id
      - is_complete: email
  - name: "Validity"
    level: warning
    rules:
      - has_min:
          column: age
          gte: 0
      - has_max:
          column: age
          lte: 120

Run the validation:

qualinkctl checks.yaml

That's it. qualinkctl loads the YAML, registers data sources, runs every check, and prints the results.

Usage

qualinkctl [OPTIONS] CONFIG

Arguments

Options

Output Formats

Human (default)

Colorized terminal output with pass/fail icons — ideal for interactive use.

qualinkctl checks.yaml

Verification PASSED: User Data Quality

  Checks: 2  |  Constraints: 4
  Passed: 4  |  Failed: 0  |  Skipped: 0
  Pass rate: 100.0%

JSON

Structured JSON output — ideal for CI/CD pipelines and downstream processing.

qualinkctl checks.yaml -f json

{
  "suite": "User Data Quality",
  "success": true,
  "metrics": {
    "total_checks": 2,
    "total_constraints": 4,
    "passed": 4,
    "failed": 0,
    "pass_rate": 1.0
  },
  "issues": []
}

Markdown

Markdown tables — ideal for CI reports, pull request comments, and documentation.

qualinkctl checks.yaml -f markdown

Writing Output to a File

Use --output / -o to write results to a file:

qualinkctl checks.yaml -f json -o results.json
qualinkctl checks.yaml -f markdown -o report.md
qualinkctl checks.yaml -f json -o s3://my-bucket/qualink/results.json
qualinkctl checks.yaml -f markdown -o gs://my-bucket/qualink/report.md

Supported filesystem URI schemes currently include s3://, gs://, gcs://, az://, abfs://, and abfss://. These are handled through PyArrow filesystem backends.

YAML-Configured Outputs

You can also define one or more output destinations directly in the YAML:

outputs:
  - path: reports/results.json
    format: json
    show_passed: true
  - uri: s3://my-bucket/qualink/results.md
    format: markdown

When you run qualinkctl checks.yaml, the CLI still prints its normal stdout output and also writes each configured output destination. If you additionally pass --output, that explicit CLI destination is written as well.

Exit Codes

qualinkctl sets the exit code based on the validation outcome, making it easy to integrate into CI/CD pipelines:

Example CI usage:

qualinkctl checks.yaml -f json -o results.json || echo "Validation failed!"

Examples

Basic run

qualinkctl checks.yaml

JSON output to stdout

qualinkctl checks.yaml -f json

Save markdown report to file

qualinkctl checks.yaml -f markdown -o report.md
qualinkctl checks.yaml -f json -o s3://my-bucket/qualink/results.json

Show all constraints (including passed)

qualinkctl checks.yaml --show-passed

Hide metrics, show only issues

qualinkctl checks.yaml --no-metrics

Disable colors (useful for log files)

qualinkctl checks.yaml --no-color -o results.txt

Debug logging

qualinkctl checks.yaml -v

Full example with all options

qualinkctl checks.yaml \
  -f json \
  -o results.json \
  --show-passed \
  --no-color \
  -v

This is useful when qualinkctl is not on your PATH or when running inside a virtual environment.

CI/CD Integration

GitHub Actions

- name: Run data quality checks
  run: |
    uv add qualink
    qualinkctl checks.yaml -f json -o results.json

Fail the pipeline on validation failure

Since qualinkctl returns exit code 1 on failure, CI runners will automatically mark the step as failed:

qualinkctl checks.yaml
# Pipeline stops here if any check fails