Metadata-Version: 2.4
Name: truero
Version: 0.2.6
Summary: Understand and clean your data before it causes problems
Home-page: https://github.com/Thisizzellie/Truero
Author: Truero
Author-email: hello@truero.ai
License: Proprietary
Project-URL: Homepage, https://www.truero.ai
Project-URL: Dashboard, https://dashboard.truero.ai
Project-URL: Source, https://github.com/Thisizzellie/Truero
Keywords: ml data-quality validation bias audit cli
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: click>=8.0
Requires-Dist: requests>=2.28
Requires-Dist: rich>=13.0
Requires-Dist: pandas>=1.5
Requires-Dist: numpy>=1.23
Requires-Dist: flask>=3.0
Requires-Dist: openpyxl>=3.0
Requires-Dist: pyarrow>=10.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 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](https://dashboard.truero.ai).

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

| OS | Recommended Method | Command / Link |
|---|---|---|
| **macOS** | Homebrew / Official PKG | • `brew install python@3.11` ([Homebrew](https://brew.sh/))<br>• [Official macOS Installer](https://www.python.org/downloads/macos/) |
| **Windows** | Official Installer / Winget | • [Official Windows Installer](https://www.python.org/downloads/windows/) *(Check "Add python.exe to PATH")*<br>• `winget install Python.Python.3.11`<br>• [Microsoft Store Python 3.11](https://apps.microsoft.com/detail/9nr50h2988sf) |
| **Linux (Ubuntu/Debian)** | APT | `sudo apt update && sudo apt install python3.11 python3.11-venv python3-pip` |
| **Linux (Fedora/RHEL)** | DNF | `sudo dnf install python3.11 python3.11-pip` |
| **Cross-Platform / Fast** | `uv` / `pyenv` | • [astral.sh/uv](https://astral.sh/uv) (`uv python install 3.11`)<br>• [github.com/pyenv/pyenv](https://github.com/pyenv/pyenv) (`pyenv install 3.11`) |

---

## Install

**Recommended (Isolated CLI via pipx):**

```bash
pipx install truero
```

**With Python 3.11+ directly:**

```bash
python3.11 -m pip install --upgrade truero
```

**In a virtual environment:**

```bash
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](https://dashboard.truero.ai) account.

### 🔑 Login Commands

```bash
# 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:

```bash
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:**
```yaml
- 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:

```bash
truero scan data.csv
```

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

Optional browser wizard (same checks, GUI):

```bash
truero web
```

## Upload to the dashboard

After a scan, the CLI asks:

```text
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

| Flag / env | Purpose |
|------------|---------|
| `--user-id` / `TRUERO_USER_ID` | Dashboard User ID (UUID) for attribution & CI/CD |
| `--api-key` / `TRUERO_API_KEY` | Truero API key for headless authentication |
| `--no-upload` | Skip dashboard upload prompt |
| `--accept-terms` | Non-interactively accept Terms & Conditions (for CI/CD) |
| `--local` | Connect CLI login to local dev dashboard (`http://localhost:5173`) |
| `--manual` | Manual token login for headless SSH environments without a browser |
| `TRUERO_API_URL` | Override backend URL (default: hosted Railway API) |
| `TRUERO_DASHBOARD_URL` | Dashboard base URL (default: `https://dashboard.truero.ai`) |
| `--api-key` / `TRUERO_API_KEY` | Internal/dev only — not required for normal installs |

## 🛡️ 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](https://dashboard.truero.ai) 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.6`)
     - 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

```bash
truero scan path/to/file.csv
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/
