Skip to content

CLI Commands

Reference for the Recce command-line tools.

Overview

Recce provides two pip packages:

  1. recce-cloud (pip install recce-cloud) - Lightweight library for Cloud operations. Cloud users only need this to connect to sessions.

  2. recce (pip install recce) - Full OSS library with local server for data validation and diffing.

recce-cloud Commands

Connect to Cloud sessions locally or upload artifacts in CI/CD pipelines.

Installation

pip install recce-cloud

Connect to Cloud sessions

Step 1: Authenticate

# Check current auth status
recce-cloud login --status

# If not logged in:
recce-cloud login

Step 2: Initialize the project

Link your local project to your Cloud organization:

recce-cloud init

Step 3: Find your session

# List all sessions
recce-cloud list

# Filter by type
recce-cloud list --type pr

Step 4: Launch the server

recce server --session-id <SESSION_ID>

The server runs locally on http://localhost:8000 but fetches state from Cloud. Your changes automatically sync back when you close the session.

CI/CD integration

Upload dbt artifacts to Cloud in your pipelines:

# CD workflow: Upload baseline after merge to main
recce-cloud upload --type prod

# CI workflow: Upload PR artifacts (auto-detected)
recce-cloud upload

Environment variables:

Platform Variable Description
GitHub GITHUB_TOKEN Authentication token (automatic in Actions)
GitLab CI_JOB_TOKEN Authentication token (automatic in CI/CD)

See Setup CI and Setup CD for complete guides.

Command reference

recce-cloud login

recce-cloud login [OPTIONS]
Option Description
--status Check current authentication status

recce-cloud init

recce-cloud init

Links your local project to a Cloud organization and project.

recce-cloud list

recce-cloud list [OPTIONS]
Option Description
--type <type> Filter by session type: pr, dev, prod

recce-cloud upload

recce-cloud upload [OPTIONS]
Option Description
--type <type> Session type: prod for baseline, omit for auto-detection
--target-path <path> Path to dbt artifacts. Default: target/
--dry-run Test configuration without uploading

recce Commands

Run data validation locally with the full OSS library.

Installation

pip install recce

Local development workflow

# Start interactive session
recce server

# Continue from saved state
recce server my_state.json

# Share with reviewer (they load in review mode)
recce server --review my_state.json

See OSS Workflow for the complete guide.

Command reference

recce server

recce server [OPTIONS] [STATE_FILE]

Arguments:

Argument Description
STATE_FILE Optional state file path. Loads if exists, creates if not.

Options:

Option Description
--session-id <id> Connect to a Cloud session by ID
--review Review mode. Uses artifacts from state file instead of target/
--port <port> Port to run the server on. Default: 8000
--api-token <token> API token for Cloud connection

Notes:

  • Runs on http://localhost:8000 by default
  • For OSS usage, requires artifacts in target/ and target-base/ unless using --review mode

recce run

Executes preset checks and saves results to a state file.

recce run [OPTIONS]
Option Description
--state-file <file> Path to state file. Default: recce_state.json
--github-pull-request-url <url> GitHub PR URL for CI context

recce summary

Generates a summary report from a state file.

recce summary <STATE_FILE>

recce debug

Verifies configuration and environment setup.

recce debug

Checks for required artifacts and warehouse connection.

recce --help

Display all available commands and options.

recce --help

Troubleshooting

Port already in use

If port 8000 is already in use, specify a different port:

recce server --port 8001

Summary fails with "state file is required for review mode"

recce summary recce-state.json
[Error] Failed to generate summary
The state file is required for review mode

The recce summary command requires artifacts embedded in the state file. State files from local sessions may not include artifacts. Export a state file from a review session or use Cloud for summary generation.