Recce Cloud CLI

Lightweight command-line tool for managing dbt artifacts with Recce Cloud in CI/CD environments.

Overview

The Recce Cloud CLI (recce-cloud) is a standalone tool designed for CI/CD pipelines that need to upload and download dbt artifacts (manifest.json and catalog.json) to/from Recce Cloud without the full recce package dependencies.

Key Features:

🚀 Lightweight - minimal dependencies for fast CI/CD execution
🤖 Auto-detection - automatically detects CI platform, repository, and PR/MR context
⬆️ Upload - push dbt artifacts to Recce Cloud sessions
⬇️ Download - pull dbt artifacts from Recce Cloud sessions
🔐 Flexible authentication - browser-based login, token-based auth, or CI tokens
🔗 Project binding - link local projects to Recce Cloud organizations
✅ Platform-specific - optimized for GitHub Actions and GitLab CI

Installation

pip install recce-cloud

Or in your CI/CD workflow:

# GitHub Actions
- name: Install recce-cloud
  run: pip install recce-cloud

# GitLab CI
install:
  script:
    - pip install recce-cloud

Quick Start

Local Development

Login to Recce Cloud:

# Browser-based login (recommended)
recce-cloud login

# Token-based login (for headless environments)
recce-cloud login --token <your-api-token>

Initialize project binding:

# Interactive project selection
recce-cloud init

# Check current status
recce-cloud status

Logout:

recce-cloud logout

GitHub Actions

Upload artifacts:

- name: Upload to Recce Cloud
  run: recce-cloud upload
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Download artifacts:

- name: Download from Recce Cloud
  run: recce-cloud download --prod --target-path target-base
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

GitLab CI

Upload artifacts:

recce-upload:
  script:
    - recce-cloud upload

Download artifacts:

recce-download:
  script:
    - recce-cloud download --prod --target-path target-base

Upload Workflows

The recce-cloud upload command supports two workflows:

1. Platform-Specific Workflow (Recommended)

For GitHub Actions and GitLab CI

Automatically creates Recce Cloud sessions using platform-specific APIs. No session ID required.

Features:

✅ Auto-creates session with touch-recce-session API
✅ Auto-detects PR/MR context and links session
✅ Notifies upload completion
✅ Works with CI-provided tokens (GITHUB_TOKEN, CI_JOB_TOKEN)

Usage:

# GitHub Actions
recce-cloud upload

# GitLab CI
recce-cloud upload

# With custom target path
recce-cloud upload --target-path custom-target

# With manual overrides
recce-cloud upload --cr 123 --type cr

Requirements:

Running in GitHub Actions or GitLab CI environment
RECCE_API_TOKEN or CI-provided token (GITHUB_TOKEN/CI_JOB_TOKEN)
dbt artifacts in target directory

2. Generic Workflow

For other CI platforms or existing sessions

Uploads to a pre-existing Recce Cloud session using session ID.

Usage:

# With session ID parameter
recce-cloud upload --session-id abc123

# With environment variable
export RECCE_SESSION_ID=abc123
recce-cloud upload

# With custom target path
recce-cloud upload --session-id abc123 --target-path my-target

Requirements:

Pre-created session ID (from Recce Cloud web app or API)
RECCE_API_TOKEN
dbt artifacts in target directory

Download Workflows

The recce-cloud download command supports two workflows:

1. Platform-Specific Workflow (Recommended)

For GitHub Actions and GitLab CI

Automatically finds and downloads artifacts from Recce Cloud sessions using platform-specific APIs. No session ID required.

Features:

✅ Auto-detects PR/MR context
✅ Supports downloading production/base session with --prod flag
✅ Works with CI-provided tokens (GITHUB_TOKEN, CI_JOB_TOKEN)

Usage:

# GitHub Actions - Download current PR session
recce-cloud download

# GitLab CI - Download current MR session
recce-cloud download

# Download production/base session
recce-cloud download --prod

# Download to custom target path
recce-cloud download --target-path target-base

# Force overwrite existing files
recce-cloud download --force

Requirements:

Running in GitHub Actions or GitLab CI environment
CI-provided token (GITHUB_TOKEN/CI_JOB_TOKEN)
Session must exist in Recce Cloud

2. Generic Workflow

For other CI platforms or specific sessions

Downloads from a specific Recce Cloud session using session ID.

Usage:

# With session ID parameter
recce-cloud download --session-id abc123

# With environment variable
export RECCE_SESSION_ID=abc123
recce-cloud download

# With custom target path
recce-cloud download --session-id abc123 --target-path my-target

# Force overwrite
recce-cloud download --session-id abc123 --force

Requirements:

Session ID (from Recce Cloud web app or API)
RECCE_API_TOKEN
Session must exist in Recce Cloud

Command Reference

`recce-cloud login`

Authenticate with Recce Cloud.

Options:

Option	Type	Default	Description
`--token`	string	-	API token for direct authentication (optional)

Usage:

# Browser-based login (opens browser for OAuth)
recce-cloud login

# Direct token authentication (for CI/headless environments)
recce-cloud login --token <your-api-token>

Notes:

Browser login opens Recce Cloud in your default browser for secure OAuth authentication
If the browser doesn't open automatically, the URL is displayed for manual access
Token-based login is useful for CI/CD environments or when browser access is unavailable
Credentials are saved to ~/.recce/profile.yml

`recce-cloud logout`

Clear stored Recce Cloud credentials.

Usage:

recce-cloud logout

`recce-cloud init`

Initialize project binding to link a local project with a Recce Cloud organization and project.

Usage:

recce-cloud init

Workflow:

Verifies you are logged in (prompts for login if not)
Lists available organizations (shows display names)
Prompts you to select an organization
Lists available projects in selected organization (excludes archived projects)
Prompts you to select a project
Saves binding to .recce/config
Optionally adds .recce/ to .gitignore

Notes:

Requires authentication (run recce-cloud login first)
Creates .recce/config file in current directory
Binding can be overridden with environment variables (RECCE_ORG, RECCE_PROJECT)

`recce-cloud status`

Display current authentication and project binding status.

Usage:

recce-cloud status

Output:

Shows logged-in user email (or "Not logged in")
Shows current project binding (organization/project or "Not bound")
Indicates configuration source (CLI flags, environment variables, or local config)

`recce-cloud upload`

Upload dbt artifacts to Recce Cloud session.

Options:

Option	Type	Default	Description
`--target-path`	path	`target`	Path to dbt target directory
`--session-id`	string	-	Session ID for generic workflow (optional)
`--cr`	integer	-	Override PR/MR number
`--type`	choice	-	Override session type: `cr`, `prod`, `dev`
`--dry-run`	flag	false	Show what would be uploaded without uploading

Environment Variables:

Variable	Required	Description
`RECCE_API_TOKEN`	Recommended	Recce Cloud API token
`RECCE_SESSION_ID`	Optional	Session ID for generic workflow
`GITHUB_TOKEN`	Explicit set	GitHub authentication (Actions)
`CI_JOB_TOKEN`	Auto-detected	GitLab authentication (CI)

Exit Codes:

Code	Description
0	Success
1	Platform not supported (platform-specific workflow)
2	Authentication error
3	File validation error
4	Upload error

`recce-cloud download`

Download dbt artifacts (manifest.json, catalog.json) from Recce Cloud session.

Options:

Option	Type	Default	Description
`--target-path`	path	`target`	Path to directory where artifacts will be downloaded
`--session-id`	string	-	Session ID for generic workflow (optional)
`--prod`	flag	false	Download production/base session
`--dry-run`	flag	false	Show what would be downloaded without downloading
`--force`, `-f`	flag	false	Overwrite existing files without prompting

Environment Variables:

Variable	Required	Description
`RECCE_API_TOKEN`	Recommended	Recce Cloud API token
`RECCE_SESSION_ID`	Optional	Session ID for generic workflow
`GITHUB_TOKEN`	Explicit set	GitHub authentication (Actions)
`CI_JOB_TOKEN`	Auto-detected	GitLab authentication (CI)

Exit Codes:

Code	Description
0	Success
1	Platform not supported (platform-specific workflow)
2	Authentication error
3	File validation error
4	Download error

Common Examples:

# Auto-find and download current PR/MR session
recce-cloud download

# Download project's production/base session
recce-cloud download --prod

# Download from specific session ID
recce-cloud download --session-id abc123

# Download prod session to target-base
recce-cloud download --prod --target-path target-base

# Force overwrite existing files
recce-cloud download --force

# Dry run - preview what would be downloaded
recce-cloud download --dry-run

`recce-cloud version`

Display the version of recce-cloud.

recce-cloud version

Authentication

The CLI supports multiple authentication methods with the following priority:

RECCE_API_TOKEN (explicit token) - Recommended for production
CI-provided tokens - GITHUB_TOKEN (Actions) or CI_JOB_TOKEN (GitLab CI)
Error if no token available

Getting API Tokens

Recce Cloud API Token:

Log in to Recce Cloud
Go to Settings → API Tokens
Create a new token
Add to CI/CD secrets as RECCE_API_TOKEN

GitHub Token:

Available as ${{ secrets.GITHUB_TOKEN }} in Actions
Must be explicitly set in env: section of your workflow

GitLab Token:

Automatically available as $CI_JOB_TOKEN in GitLab CI
No additional configuration needed

Auto-Detection

The CLI automatically detects your CI environment:

Detected Information

Information	GitHub Actions	GitLab CI
Platform	✅ `github-actions`	✅ `gitlab-ci`
Repository	✅ `owner/repo`	✅ `group/project`
PR/MR Number	✅ From event payload	✅ From `CI_MERGE_REQUEST_IID`
PR/MR URL	✅ Constructed	✅ Constructed (self-hosted support)
Commit SHA	✅ `GITHUB_SHA`	✅ `CI_COMMIT_SHA`
Source Branch	✅ `GITHUB_HEAD_REF`	✅ `CI_MERGE_REQUEST_SOURCE_BRANCH_NAME`
Base Branch	✅ `GITHUB_BASE_REF`	✅ `CI_MERGE_REQUEST_TARGET_BRANCH_NAME`
Session Type	✅ Auto-determined	✅ Auto-determined
Access Token	✅ `GITHUB_TOKEN`	✅ `CI_JOB_TOKEN`

Manual Overrides

You can override auto-detected values:

# Override PR/MR number
recce-cloud upload --cr 456

# Override session type
recce-cloud upload --type prod

# Multiple overrides
recce-cloud upload --cr 789 --type cr

# Dry run - preview what would be uploaded
recce-cloud upload --dry-run

CI/CD Integration Examples

GitHub Actions - Upload Workflow

name: Recce CI - Upload

on:
  pull_request:
    branches: [main]

jobs:
  recce:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: "3.11"

      - name: Install dependencies
        run: |
          pip install dbt-core dbt-postgres recce-cloud

      - name: Build dbt project
        run: |
          dbt deps
          dbt build
          dbt docs generate

      - name: Upload to Recce Cloud
        run: recce-cloud upload
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

GitHub Actions - Download Workflow

name: Recce CI - Download

on:
  pull_request:
    branches: [main]

jobs:
  recce:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: "3.11"

      - name: Install dependencies
        run: |
          pip install dbt-core dbt-postgres recce-cloud

      # Download production/base artifacts
      - name: Download base artifacts from Recce Cloud
        run: recce-cloud download --prod --target-path target-base
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      # Build current PR version
      - name: Build dbt project (current)
        run: |
          dbt deps
          dbt build
          dbt docs generate

      # Upload current PR artifacts
      - name: Upload to Recce Cloud
        run: recce-cloud upload
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

GitLab CI - Upload Workflow

stages:
  - build
  - upload

dbt-build:
  stage: build
  image: python:3.11-slim
  script:
    - pip install dbt-core dbt-postgres
    - dbt deps
    - dbt build
    - dbt docs generate
  artifacts:
    paths:
      - target/

recce-upload:
  stage: upload
  image: python:3.11-slim
  script:
    - pip install recce-cloud
    - recce-cloud upload
  dependencies:
    - dbt-build
  only:
    - merge_requests
    - main

GitLab CI - Download Workflow

stages:
  - download
  - build
  - upload

recce-download-base:
  stage: download
  image: python:3.11-slim
  script:
    - pip install recce-cloud
    - recce-cloud download --prod --target-path target-base
  artifacts:
    paths:
      - target-base/
  only:
    - merge_requests

dbt-build:
  stage: build
  image: python:3.11-slim
  script:
    - pip install dbt-core dbt-postgres
    - dbt deps
    - dbt build
    - dbt docs generate
  artifacts:
    paths:
      - target/
  only:
    - merge_requests

recce-upload:
  stage: upload
  image: python:3.11-slim
  script:
    - pip install recce-cloud
    - recce-cloud upload
  dependencies:
    - dbt-build
  only:
    - merge_requests

Generic CI Platform

For other CI platforms, use the generic workflow with session ID:

# Upload
- name: Upload to Recce Cloud
  script:
    - pip install recce-cloud
    - recce-cloud upload --session-id ${SESSION_ID}
  environment:
    RECCE_API_TOKEN: ${RECCE_API_TOKEN}
    SESSION_ID: ${SESSION_ID}

# Download
- name: Download from Recce Cloud
  script:
    - pip install recce-cloud
    - recce-cloud download --session-id ${SESSION_ID}
  environment:
    RECCE_API_TOKEN: ${RECCE_API_TOKEN}
    SESSION_ID: ${SESSION_ID}

Troubleshooting

Common Issues

1. Missing dbt artifacts

Error: Invalid target path: target
Please provide a valid target path containing manifest.json and catalog.json.

Solution: Ensure dbt docs generate has been run successfully before upload.

dbt build
dbt docs generate  # Required!
recce-cloud upload

2. Authentication failed

Error: No authentication token provided
Set RECCE_API_TOKEN environment variable or ensure CI token is available

Solution: Token requirements depend on your workflow type:

For Generic Workflow (with --session-id):

Always requires explicit RECCE_API_TOKEN

# Set token and use session ID
export RECCE_API_TOKEN=your_token_here
recce-cloud upload --session-id abc123
recce-cloud download --session-id abc123

For Platform-Specific Workflow:

GitHub CI

Use GITHUB_TOKEN (explicitly set)

env:
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

3. Platform not supported

Error: Platform-specific upload requires GitHub Actions or GitLab CI environment
Detected platform: unknown

Solution: Use generic workflow with session ID, or run in supported CI platform.

recce-cloud upload --session-id abc123

4. Session not found

Error: Session ID abc123 does not belong to any organization.

Solution: Verify session ID is correct and accessible with your API token.

5. GitLab self-hosted instance

The CLI automatically detects self-hosted GitLab instances using CI_SERVER_URL.

# No additional configuration needed
recce-upload:
  script:
    - recce-cloud upload

6. Target path already exists (download)

Error: Target path already exists: target
Use --force to overwrite existing directory

Solution: Use --force flag to overwrite existing files, or choose a different target path.

recce-cloud download --force
# OR
recce-cloud download --target-path target-new

7. No production session available

Error: No production session found for this project

Solution: Upload a production session first, or use a specific session ID.

# Upload production session (on main branch)
recce-cloud upload --type prod

# Or download from specific session
recce-cloud download --session-id abc123

Debug Mode

Enable verbose logging for troubleshooting:

# Set log level to DEBUG
export RECCE_LOG_LEVEL=DEBUG
recce-cloud upload

Architecture

Platform-Specific APIs

The CLI uses platform-specific API endpoints for auto-session creation:

GitHub Actions:

POST /api/v2/github/{repository}/touch-recce-session
POST /api/v2/github/{repository}/upload-completed

GitLab CI:

POST /api/v2/gitlab/{project_path}/touch-recce-session
POST /api/v2/gitlab/{project_path}/upload-completed

Upload Process

Platform-Specific Workflow:

Detect CI platform and extract context
Validate dbt artifacts
Extract adapter type from manifest
Authenticate with Recce Cloud API
Call touch-recce-session (creates or updates session)
Upload manifest.json to presigned S3 URL
Upload catalog.json to presigned S3 URL
Call upload-completed (notifies Recce Cloud)

Generic Workflow:

Detect CI platform (optional)
Validate dbt artifacts
Extract adapter type from manifest
Authenticate with Recce Cloud API
Get session info (org_id, project_id)
Get presigned upload URLs
Upload manifest.json to S3
Upload catalog.json to S3
Update session metadata

Download Process

Platform-Specific Workflow:

Detect CI platform and extract context
Authenticate with Recce Cloud API
Call download API with PR/MR context
Get presigned download URLs and session ID
Create target directory (if needed)
Download manifest.json from S3
Download catalog.json from S3

Generic Workflow (Session ID):

Authenticate with Recce Cloud API
Get session info (org_id, project_id)
Get presigned download URLs by session ID
Create target directory (if needed)
Download manifest.json from S3
Download catalog.json from S3

Development

Running Tests

# Install development dependencies
pip install -e .[dev]

# Run tests
pytest tests/recce_cloud/

# Run with coverage
pytest --cov=recce_cloud --cov-report=html tests/recce_cloud/

# Run specific test file
pytest tests/recce_cloud/test_platform_clients.py

Code Quality

# Format code
make format

# Run quality checks
make check

# Run all checks and tests
make test

Support

Documentation: docs.reccehq.com
Issues: GitHub Issues
Community: Recce Slack
Email: support@reccehq.com

License

Apache License 2.0 - See LICENSE file for details.

Metadata

Release files for recce-cloud-nightly 1.32.0.20260127

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for recce-cloud-nightly 1.32.0.20260127
File	Size	Uploaded
recce_cloud_nightly-1.32.0.20260127.tar.gz	194.1 kB	Jan 27, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for recce-cloud-nightly 1.32.0.20260127
File	Interpreter	ABI	Platform	Reset
recce_cloud_nightly-1.32.0.20260127-py3-none-any.whl 208.2 kB Jan 27, 2026	Python 3	none	any	Details

Total release size: 402.3 kB

Release files / recce_cloud_nightly-1.32.0.20260127.tar.gz

Download URL	recce_cloud_nightly-1.32.0.20260127.tar.gz
Size	194.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`700c7b63c07f7ddc8e85bf63c7a0c10d54a2fef6c049c0bda7400f019d5c5045`
BLAKE2b-256 checksum How to use checksums	`6d196883cf932c56f3680faa8c12cfe6e0f1b8f9339e16085cbaa6c97847983a`
Upload date	Jan 27, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.10.19`

Release files / recce_cloud_nightly-1.32.0.20260127-py3-none-any.whl

Download URL	recce_cloud_nightly-1.32.0.20260127-py3-none-any.whl
Size	208.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`6373f02ef859a1e9a0a456542ce6d521ff9b0c183ade0ce5f394edf1e9d484c8`
BLAKE2b-256 checksum How to use checksums	`5796089ee45ee89305b83c9a391053873ea6194df2a80b52df16e4d3be0a6a53`
Upload date	Jan 27, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.10.19`