Truero CLI

Understand and clean your data before it causes problems.

Run data-quality and ML validation checks on your machine, then optionally upload the report (not your raw file) to the Truero dashboard.

Prerequisites & Python Setup

• Python Version: Python 3.11+ is recommended (Python 3.10+ supported).
• macOS Note: Avoid the default system Python 3.9 (its bundled LibreSSL causes SSL warnings and syntax incompatibilities with modern libraries). Use Homebrew Python (brew install python@3.11), pyenv, or pipx.

Need to install Python 3.11?

Install

Recommended (Isolated CLI via pipx):

pipx install truero

With Python 3.11+ directly:

python3.11 -m pip install --upgrade truero

In a virtual environment:

python3.11 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
python -m pip install --upgrade truero

Authentication & Identity

Truero CLI requires a one-time login to link your terminal session with your Truero Dashboard account.

🔑 Login Commands

# Log in via your browser (starts local loopback handshake)
truero login

# Check active session and machine telemetry status
truero whoami

# Sign out and remove local credentials
truero logout

🤖 Automated CI/CD Pipelines (Headless Execution)

In automated CI/CD pipelines (GitHub Actions, GitLab CI, Jenkins, Docker containers), provide your credentials via environment variables so scans run completely unattended:

export TRUERO_USER_ID="YOUR-USER-UUID"
export TRUERO_API_KEY="YOUR-API-KEY"  # Optional
truero scan data/dataset.csv --no-upload --accept-terms

GitHub Actions Example:

- name: Run Truero Data Validation
  env:
    TRUERO_USER_ID: ${{ secrets.TRUERO_USER_ID }}
  run: truero scan data/training_dataset.csv --no-upload --accept-terms

Quick start

In the same environment where you installed Truero:

truero scan data.csv

Supported files: CSV, JSON, Excel (.xlsx / .xls), Parquet.

Optional browser wizard (same checks, GUI):

truero web

Custom rules

Custom rules are optional and run in addition to the normal Truero checks. Pass --custom-rules and the CLI asks which rules apply to which columns:

truero scan data.csv --custom-rules

Reuse those picks on a later scan with a saved profile:

truero scan data.csv --profile NAME

Write the rows a custom rule flagged to a CSV:

truero scan data.csv --custom-rules --export-flags flags.csv

See the rule list:

truero rules list

Upload to the dashboard

After a scan, the CLI asks:

Upload report to Truero dashboard? [Y/n]:

1. Type Y (or press Enter) to upload, or n to skip.
2. Since you are authenticated via truero login, the report is automatically linked to your account.
3. Upload sends the report summary only — never your raw dataset.

Optional configuration & CLI Flags

🛡️ Privacy, Security & Safe Telemetry Notice

Truero is designed with privacy, safety, and local-first execution at its core:

1. Your Dataset Stays on Your Machine:

   • Validation checks (duplicates, missing values, outliers, data types, correlation, silent failures, custom rules) execute 100% locally.
   • Raw data files, row values, personal records, and column contents are never uploaded to Truero servers. Only summary issue counts and metadata are sent if you explicitly choose to upload a report.

2. Why Login / Signup is Required:

   • To distinguish genuine human developers from automated web scrapers, bots, and PyPI mirrors.
   • To securely link your local CLI runs to your Truero Dashboard account.

3. What System Telemetry is Collected:

   • We capture only non-invasive, standard environment metadata to identify installation environments:
     • Operating System & release version (e.g. macOS 15.1, Ubuntu 22.04)
     • CPU architecture (e.g. arm64, x86_64)
     • Python runtime & CLI version (e.g. CPython 3.11.8, truero 0.2.9)
     • Local timezone & system locale (e.g. Europe/London, en_GB)
     • Anonymous machine fingerprint (deterministic SHA-256 hash — no raw hardware serials or MAC addresses are stored)
     • CI environment flag (distinguishes automated pipelines from interactive terminals)
   • Zero PII, zero credentials, zero source code, and zero dataset content are collected.

Useful commands

truero scan path/to/file.csv
truero scan path/to/file.csv --custom-rules
truero rules list
truero login
truero whoami
truero logout
truero web
truero config show

Links

• Website: https://www.truero.ai
• Dashboard: https://dashboard.truero.ai
• GitHub: https://github.com/Thisizzellie/Truero
• PyPI: https://pypi.org/project/truero/