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 - works with CI tokens or explicit API tokens
- ✅ 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
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-sessionAPI - ✅ 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
--prodflag - ✅ 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 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_TOKENin 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-sessionPOST /api/v2/github/{repository}/upload-completed
GitLab CI:
POST /api/v2/gitlab/{project_path}/touch-recce-sessionPOST /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.
1 maintainer
Metadata
1 maintainer
Release files for recce-cloud-nightly 1.31.0.20251226
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| recce_cloud_nightly-1.31.0.20251226.tar.gz | 23.0 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| recce_cloud_nightly-1.31.0.20251226-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 63.7 kB
Release files / recce_cloud_nightly-1.31.0.20251226.tar.gz
| Download URL | recce_cloud_nightly-1.31.0.20251226.tar.gz |
|---|---|
| Size | 23.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b3a8ea7f0103a39a792ad08fbcccdaa60fd7a43257649ed438efbdbc54ac0d6d
|
|
BLAKE2b-256 checksum How to use checksums |
1029bcae17f0236f26635d65e35bd81625a01321ddd1656b9b913193f4ac5cad
|
| Upload date | |
|
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.31.0.20251226-py3-none-any.whl
| Download URL | recce_cloud_nightly-1.31.0.20251226-py3-none-any.whl |
|---|---|
| Size | 40.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e4e657923f54e5c089bd1e4cf1db7778237f851b869f8fb0e56a834f293ffc7c
|
|
BLAKE2b-256 checksum How to use checksums |
e62414035ca8bc009ff5918661dbc1c3cb4443d16b0ee6e862653dc83b4113cc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.10.19
|
