Recce

https://docs.reccehq.com
Admin
Recce is a data review agent for dbt pull requests that automates data validation by comparing...
Tokens:26,224
Snippets:427
Trust Score:6.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Initialize Recce setup

Source: https://docs.reccehq.com/setup-guides/claude-plugin

Run the setup command within a dbt project to configure artifacts and start the MCP server.

```text
/recce-setup
```

--------------------------------

### Install recce-cloud

Source: https://docs.reccehq.com/using-recce/cli-commands

Install the lightweight library for Cloud operations.

```bash
pip install recce-cloud
```

--------------------------------

### Install Recce plugin

Source: https://docs.reccehq.com/setup-guides/claude-plugin

Install the plugin using the command line or the interactive installer.

```text
/plugin install recce-quickstart@recce-claude-plugin
```

```text
/plugin
```

--------------------------------

### Verify installation

Source: https://docs.reccehq.com/setup-guides/claude-plugin

Check the installed plugins list to confirm the presence of the Recce plugin.

```text
/plugin
```

--------------------------------

### Install Dependencies

Source: https://docs.reccehq.com/getting-started/jaffle-shop-tutorial

Install the required Python packages for dbt and Recce.

```shell
pip install -r requirements.txt
pip install recce
```

--------------------------------

### Install Recce OSS

Source: https://docs.reccehq.com/AGENTS

Install the Recce CLI tool using uv or pip within the dbt project environment.

```bash
uv tool install recce
# or
pip install recce
```

--------------------------------

### Launch the Recce server

Source: https://docs.reccehq.com/using-recce/cli-commands

Start the local server connected to a specific Cloud session.

```bash
recce server --session-id <SESSION_ID>
```

--------------------------------

### Install Recce Claude Plugin

Source: https://docs.reccehq.com/setup-guides/mcp-server

Commands to install and initialize the Recce plugin within the Claude environment.

```text
/plugin install recce-quickstart@recce-claude-plugin
/recce-setup
```

--------------------------------

### Configure Claude Code via Plugin

Source: https://docs.reccehq.com/setup-guides/mcp-server

Use the Recce plugin for guided setup and installation.

```shell
/plugin marketplace add DataRecce/recce-claude-plugin
/plugin install recce-quickstart@recce-claude-plugin
/recce-setup
```

--------------------------------

### Debug Recce Configuration

Source: https://docs.reccehq.com/using-recce/cli-commands

Verify the environment setup and warehouse connection.

```bash
recce debug
```

--------------------------------

### Install Recce with MCP support

Source: https://docs.reccehq.com/setup-guides/mcp-server

Install the package with the necessary MCP extra dependency.

```shell
pip install 'recce[mcp]'
```

--------------------------------

### Start Recce Server

Source: https://docs.reccehq.com/getting-started/oss-setup

Launch the Recce web interface to begin data validation.

```shell
recce server
```

--------------------------------

### Install Recce

Source: https://docs.reccehq.com/getting-started/oss-setup

Install the Recce package within your dbt project's virtual environment.

```shell
pip install recce
```

--------------------------------

### Troubleshooting commands

Source: https://docs.reccehq.com/setup-guides/claude-plugin

Commands used to verify installation, check versions, and configure the MCP server.

```text
claude --version
```

```text
pip install 'recce[mcp]'
```

```text
RECCE_MCP_PORT=8085
```

```text
/recce-setup
```

--------------------------------

### Launch Recce in review mode

Source: https://docs.reccehq.com/technical-concepts/state-file

Starts the server in review mode, utilizing dbt artifacts embedded within the provided state file instead of local directories.

```bash
recce server --review my_recce_state.json
```

--------------------------------

### Launch Recce with a state file

Source: https://docs.reccehq.com/technical-concepts/state-file

Starts the Recce server using a specific state file. If the file does not exist, a new one is created.

```bash
recce server my_recce_state.json
```

--------------------------------

### recce debug

Source: https://docs.reccehq.com/using-recce/cli-commands

Verifies the current configuration and environment setup.

```APIDOC
## recce debug

### Description
Verifies configuration and environment setup, checking for required artifacts and warehouse connection.

### Usage
`recce debug`
```

--------------------------------

### Summary Command Error Example

Source: https://docs.reccehq.com/using-recce/cli-commands

Example of an error message when generating a summary without proper artifacts.

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

--------------------------------

### Manage Recce Server Sessions

Source: https://docs.reccehq.com/using-recce/cli-commands

Commands to start the Recce server, load existing states, or initiate review mode.

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

--------------------------------

### Example recce run Output

Source: https://docs.reccehq.com/collaboration/preset-checks

The console output displayed after executing preset checks.

```text
───────────────────────────────── DBT Artifacts ─────────────────────────────────
Base:
    Manifest: 2024-04-10 08:54:41.546402+00:00
    Catalog:  2024-04-10 08:54:42.251611+00:00
Current:
    Manifest: 2024-04-22 03:24:11.262489+00:00
    Catalog:  2024-04-10 06:15:13.813125+00:00
───────────────────────────────── Preset checks ─────────────────────────────────
                            Recce Preset Checks
──────────────────────────────────────────────────────────────────────────────
Status      Name                 Type         Execution Time   Failed Reason
──────────────────────────────────────────────────────────────────────────────
[Success]   Query of customers   Query Diff   0.10 seconds     N/A
──────────────────────────────────────────────────────────────────────────────
The state file is stored at [recce_state.json]
```

--------------------------------

### Configure Query Diff Checks

Source: https://docs.reccehq.com/technical-concepts/configuration

Example for comparing query results between environments, optionally using primary keys for warehouse-side diffing.

```yaml
checks:
  - name: Customer data diff
    description: Compare customer data between environments
    type: query_diff
    params:
      sql_template: select * from {{ ref("customers") }}
      primary_keys:
      - customer_id
```

--------------------------------

### Configure Lineage Diff Checks

Source: https://docs.reccehq.com/technical-concepts/configuration

Example for comparing lineage structure using node selection syntax.

```yaml
checks:
  - name: Lineage diff for modified models
    description: Check lineage changes for modified models and downstream
    type: lineage_diff
    params:
       select: state:modified+
       exclude: tag:dev
```

--------------------------------

### Upload with external artifact sources

Source: https://docs.reccehq.com/setup-guides/setup-cd

Example workflow for downloading artifacts from an external source before uploading to Recce Cloud.

```yaml
# GitHub example
- name: Download from dbt Cloud
  run: |
    # Your download logic here
    # Artifacts should end up in target/ directory

- name: Upload to Recce Cloud
  run: |
    pip install recce-cloud
    recce-cloud upload --type prod
```

--------------------------------

### Configure Schema Diff Checks

Source: https://docs.reccehq.com/technical-concepts/configuration

Examples for comparing schema structures using node selectors or specific node IDs.

```yaml
checks:
  - name: Schema diff for modified models
    description: Check schema changes for modified models and downstream
    type: schema_diff
    params:
       select: state:modified+
       exclude: tag:dev
```

```yaml
checks:
  - name: Schema diff for customers
    description: Check schema for customers model
    type: schema_diff
    params:
      node_id: model.jaffle_shop.customers
```

--------------------------------

### Configure Custom Query Checks

Source: https://docs.reccehq.com/technical-concepts/configuration

Example for executing a custom SQL query using Jinja templating.

```yaml
checks:
  - name: Customer count
    description: Get total customer count
    type: query
    params:
       sql_template: select count(*) from {{ ref("customers") }}
```

--------------------------------

### Resume Recce Session

Source: https://docs.reccehq.com/using-recce/oss-workflow

Start the Recce server using a previously saved state file to resume work.

```bash
recce server recce_issue_123.json
```

--------------------------------

### Resolve port conflicts

Source: https://docs.reccehq.com/setup-guides/mcp-server

Identify processes using the default port and start the server on an alternative port.

```shell
# Check what's using port 8000
lsof -i :8000

# Use a different port
recce mcp-server --sse --port 8001
```

--------------------------------

### Configure Row Count Diff Checks

Source: https://docs.reccehq.com/technical-concepts/configuration

Examples for comparing row counts using either node selectors or specific node names.

```yaml
checks:
  - name: Row count for modified tables
    description: Check row counts for all modified table models
    type: row_count_diff
    params:
       select: state:modified,config.materialized:table
       exclude: tag:dev
```

```yaml
checks:
  - name: Row count for key models
    description: Check row counts for customers and orders
    type: row_count_diff
    params:
      node_names: ['customers', 'orders']
```

--------------------------------

### Set up Virtual Environment

Source: https://docs.reccehq.com/getting-started/jaffle-shop-tutorial

Create and activate a Python virtual environment for the project.

```shell
python -m venv venv
source venv/bin/activate
```

--------------------------------

### Initialize recce-cloud project

Source: https://docs.reccehq.com/using-recce/cli-commands

Link a local project to a Cloud organization.

```bash
recce-cloud init
```

--------------------------------

### Run Recce OSS Workflow

Source: https://docs.reccehq.com/AGENTS

Execute preset checks and launch the server interface from the dbt project root.

```bash
recce run
recce server
```

--------------------------------

### Build Base Environment

Source: https://docs.reccehq.com/getting-started/jaffle-shop-tutorial

Generate the baseline production data and artifacts.

```shell
dbt seed --target prod
dbt run --target prod
dbt docs generate --target prod --target-path ./target-base
```

--------------------------------

### recce-cloud init

Source: https://docs.reccehq.com/using-recce/cli-commands

Initializes the project by linking the local directory to a Recce Cloud organization and project.

```APIDOC
## recce-cloud init

### Description
Links your local project to a Cloud organization and project.

### Usage
`recce-cloud init`
```

--------------------------------

### Connect to Cloud via CLI

Source: https://docs.reccehq.com/collaboration/share

Initiate the cloud connection and authorization process directly from the terminal.

```bash
recce connect-to-cloud
```

--------------------------------

### recce server

Source: https://docs.reccehq.com/using-recce/cli-commands

Starts an interactive Recce server session to perform data validation.

```APIDOC
## recce server

### Description
Starts an interactive server session. By default, it runs on http://localhost:8000 and requires artifacts in target/ and target-base/ directories.

### Usage
`recce server [OPTIONS] [STATE_FILE]`

### Arguments
- **STATE_FILE** (string) - Optional - Path to the state file. Loads if exists, creates if not.

### Options
- **--session-id** (string) - Optional - Connect to a Cloud session by ID.
- **--review** (boolean) - Optional - Review mode. Uses artifacts from state file instead of target/.
- **--port** (integer) - Optional - Port to run the server on. Default: 8000.
- **--api-token** (string) - Optional - API token for Cloud connection.
```

--------------------------------

### Model-wide Changes

Source: https://docs.reccehq.com/what-you-can-explore/change-classification

Examples of changes that affect all downstream models due to modifications in filtering or granularity.

```diff
select
    user_id,
    order_date
from
    {{ ref("orders") }}
++ where status = 'completed'
```

```diff
select
    user_id,
++  order_date,
    count(*) as total_orders
from
    {{ ref("orders") }}
-- group by user_id
++ group by user_id, order_date
```

--------------------------------

### Display Recce Help

Source: https://docs.reccehq.com/using-recce/cli-commands

Show all available commands and options.

```bash
recce --help
```

--------------------------------

### Execute Preset Checks via CLI

Source: https://docs.reccehq.com/collaboration/preset-checks

Run all configured preset checks from the command line.

```bash
recce run
```

--------------------------------

### Column Changes

Source: https://docs.reccehq.com/what-you-can-explore/change-classification

Examples of column-level modifications that only impact downstream models referencing the specific columns.

```diff
select
    user_id,
--  status,
    order_date,
from
    {{ ref("orders") }}
```

```diff
select
    user_id,
--  status
++  order_status
from
    {{ ref("orders") }}
```

```diff
select
    user_id,
--  discount
++  coalesce(discount, 0) as discount
from
    {{ ref("orders") }}
```

--------------------------------

### View Preset Check Results

Source: https://docs.reccehq.com/collaboration/preset-checks

Launch the Recce server using the state file generated by recce run to inspect check results.

```bash
recce server recce_state.json
```

--------------------------------

### Build Development Environment

Source: https://docs.reccehq.com/getting-started/jaffle-shop-tutorial

Run dbt commands to update the development artifacts.

```shell
dbt seed
dbt run
dbt docs generate
```

--------------------------------

### Verify dbt configuration locally

Source: https://docs.reccehq.com/setup-guides/environment-setup

Run this command to test the connection and configuration for the CI target.

```shell
dbt debug --target ci
```

--------------------------------

### recce-cloud login command reference

Source: https://docs.reccehq.com/using-recce/cli-commands

Reference for the login command options.

```bash
recce-cloud login [OPTIONS]
```

--------------------------------

### Clone Jaffle Shop Repository

Source: https://docs.reccehq.com/getting-started/jaffle-shop-tutorial

Download the sample dbt project from GitHub.

```shell
git clone git@github.com:dbt-labs/jaffle_shop_duckdb.git
cd jaffle_shop_duckdb
```

--------------------------------

### Generate Base Environment Artifacts

Source: https://docs.reccehq.com/getting-started/oss-setup

Create artifacts for the production state by checking out the main branch and generating dbt documentation.

```shell
git checkout main
dbt docs generate --target-path ./target-base
```

--------------------------------

### recce-cloud upload command reference

Source: https://docs.reccehq.com/using-recce/cli-commands

Reference for the upload command options.

```bash
recce-cloud upload [OPTIONS]
```

--------------------------------

### Apply dbt --sample for deterministic data windows

Source: https://docs.reccehq.com/setup-guides/environment-advanced

Use absolute date ranges to ensure both base and current builds process identical data windows. Requires dbt 1.10 or higher and configured event_time on source tables.

```bash
# Adjust dates to match your data range — both builds must use the same window
dbt build --target pr_base    --sample="{'start': '2025-02-01', 'end': '2025-02-28'}"
dbt build --target pr_current --sample="{'start': '2025-02-01', 'end': '2025-02-28'}"
```

--------------------------------

### Run Recce in Review Mode

Source: https://docs.reccehq.com/using-recce/oss-workflow

Launch the Recce server in review mode using a state file provided by a submitter.

```bash
recce server --review <state_file>
```

--------------------------------

### Upload Dev Session via CLI

Source: https://docs.reccehq.com/using-recce/data-developer

Uploads local dbt artifacts to Recce Cloud to initiate a development session for validation.

```bash
recce-cloud upload --type dev
```

--------------------------------

### Visualize environment comparison flow

Source: https://docs.reccehq.com/setup-guides/environment-advanced

Mermaid diagrams illustrating the difference between shared production base and session-based PR comparison.

```mermaid
graph LR
    P1["Production<br/>(target: prod)<br/>→ takes 'if' branch"] --> R1["Recce"]
    C1["PR Current<br/>(target: ci)<br/>→ takes 'else' branch"] --> R1
    R1 --> FA["False alarm:<br/>different SQL branches"]
```

```mermaid
graph LR
    P2["Session Base<br/>(target: pr_base)<br/>→ takes 'else' branch"] --> R2["Recce"]
    C2["PR Current<br/>(target: pr_current)<br/>→ takes 'else' branch"] --> R2
    R2 --> OK["Same SQL branches:<br/>differences = real code changes"]
```

--------------------------------

### recce-cloud list command reference

Source: https://docs.reccehq.com/using-recce/cli-commands

Reference for the list command options.

```bash
recce-cloud list [OPTIONS]
```

--------------------------------

### Upload State File via CLI

Source: https://docs.reccehq.com/collaboration/share

Use the CLI to upload a state file for automated workflows or CI pipelines.

```bash
recce share <your_state_file>

# With API token
recce share --api-token <your_api_token> <your_state_file>
```

--------------------------------

### Authenticate with recce-cloud

Source: https://docs.reccehq.com/using-recce/cli-commands

Check authentication status or initiate the login process.

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

# If not logged in:
recce-cloud login
```

--------------------------------

### Upload artifacts to Cloud

Source: https://docs.reccehq.com/using-recce/cli-commands

Upload dbt artifacts to Cloud for CI/CD workflows.

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

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

--------------------------------

### Generate dbt artifacts

Source: https://docs.reccehq.com/using-recce/data-developer

Run these commands to prepare the necessary artifacts for Recce before uploading a development session.

```bash
dbt build && dbt docs generate
```

--------------------------------

### Configure GitHub Actions for Base Metadata

Source: https://docs.reccehq.com/setup-guides/setup-cd

Defines a workflow to build dbt artifacts and upload them to Recce Cloud on push to main or via schedule.

```yaml
name: Update Base Metadata

on:
  push:
    branches: ["main"]
  schedule:
    - cron: "0 2 * * *"
  workflow_dispatch:

concurrency:
  group: ${{ github.workflow }}
  cancel-in-progress: true

jobs:
  update-base-session:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    permissions:
      contents: read

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"
          cache: "pip"

      - name: Install dependencies
        run: pip install -r requirements.txt

      - name: Prepare dbt artifacts
        run: |
          dbt deps
          dbt build --target prod
          dbt docs generate --target prod
        env:
          SNOWFLAKE_ACCOUNT: ${{ secrets.SNOWFLAKE_ACCOUNT }}
          SNOWFLAKE_USER: ${{ secrets.SNOWFLAKE_USER }}
          SNOWFLAKE_PASSWORD: ${{ secrets.SNOWFLAKE_PASSWORD }}
          SNOWFLAKE_DATABASE: ${{ secrets.SNOWFLAKE_DATABASE }}
          SNOWFLAKE_WAREHOUSE: ${{ secrets.SNOWFLAKE_WAREHOUSE }}

      - name: Upload to Recce Cloud
        run: |
          pip install recce-cloud
          recce-cloud upload --type prod
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

--------------------------------

### Create base workflow for dbt Cloud CD

Source: https://docs.reccehq.com/setup-guides/dbt-cloud-setup

This GitHub Actions workflow retrieves production artifacts from a dbt Cloud CD job and uploads them to Recce Cloud as the production baseline.

```yaml
name: Update Base Metadata (dbt Cloud)

on:
  push:
    branches: [main]
  workflow_dispatch:

env:
  DBT_CLOUD_API_BASE: "https://cloud.getdbt.com/api/v2/accounts/${{ secrets.DBT_CLOUD_ACCOUNT_ID }}"
  DBT_CLOUD_API_TOKEN: ${{ secrets.DBT_CLOUD_API_TOKEN }}

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

      - uses: actions/setup-python@v5
        with:
          python-version: "3.10"

      - name: Install recce-cloud
        run: pip install recce-cloud

      - name: Retrieve artifacts from CD job
        env:
          DBT_CLOUD_CD_JOB_ID: ${{ secrets.DBT_CLOUD_CD_JOB_ID }}
        run: |
          set -eo pipefail
          CD_RUNS_URL="${DBT_CLOUD_API_BASE}/runs/?job_definition_id=${DBT_CLOUD_CD_JOB_ID}&order_by=-id&limit=1"
          CD_RUNS_RESPONSE=$(curl -sSf -H "Authorization: Bearer ${DBT_CLOUD_API_TOKEN}" "${CD_RUNS_URL}")
          DBT_CLOUD_CD_RUN_ID=$(echo "${CD_RUNS_RESPONSE}" | jq -r ".data[0].id")
          mkdir -p target
          for artifact in manifest.json catalog.json; do
            ARTIFACT_URL="${DBT_CLOUD_API_BASE}/runs/${DBT_CLOUD_CD_RUN_ID}/artifacts/${artifact}"
            curl -sSf -H "Authorization: Bearer ${DBT_CLOUD_API_TOKEN}" "${ARTIFACT_URL}" -o "target/${artifact}"
          done

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

--------------------------------

### Configure Claude Code via SSE

Source: https://docs.reccehq.com/setup-guides/mcp-server

Run the Recce server in SSE mode and connect via HTTP.

```shell
cd my-dbt-project/
recce mcp-server --sse
```

```shell
cd my-dbt-project/
claude mcp add --transport sse --scope project recce http://localhost:8000/sse
```

--------------------------------

### recce run

Source: https://docs.reccehq.com/using-recce/cli-commands

Executes preset checks and saves the results to a state file.

```APIDOC
## recce run

### Description
Executes preset checks and saves results to a state file.

### Usage
`recce run [OPTIONS]`

### Options
- **--state-file** (string) - Optional - Path to state file. Default: recce_state.json.
- **--github-pull-request-url** (string) - Optional - GitHub PR URL for CI context.
```

--------------------------------

### Configure profiles.yml for PR targets

Source: https://docs.reccehq.com/setup-guides/environment-advanced

Define pr_base and pr_current targets in your profiles.yml to mirror CI environment settings.

```yaml
# profiles.yml
jaffle_shop:
  outputs:
    pr_base:
      type: snowflake
      account: "{{ env_var('SNOWFLAKE_ACCOUNT') }}"
      user: "{{ env_var('SNOWFLAKE_USER') }}"
      password: "{{ env_var('SNOWFLAKE_PASSWORD') }}"
      database: analytics
      warehouse: COMPUTE_WH
      schema: "{{ env_var('SNOWFLAKE_SCHEMA_BASE') }}"
      threads: 4

    pr_current:
      type: snowflake
      account: "{{ env_var('SNOWFLAKE_ACCOUNT') }}"
      user: "{{ env_var('SNOWFLAKE_USER') }}"
      password: "{{ env_var('SNOWFLAKE_PASSWORD') }}"
      database: analytics
      warehouse: COMPUTE_WH
      schema: "{{ env_var('SNOWFLAKE_SCHEMA_CURRENT') }}"
      threads: 4
```

--------------------------------

### Run Query Diff

Source: https://docs.reccehq.com/getting-started/jaffle-shop-tutorial

Execute a SQL query in the Recce interface to compare data between environments.

```sql
select * from {{ ref("orders") }} order by 1
```

--------------------------------

### Execute Schema Cleanup

Source: https://docs.reccehq.com/setup-guides/environment-best-practices

Run the cleanup macro via the dbt CLI by providing the schema name as an argument.

```bash
dbt run-operation clear_schema --args "{'schema_name': 'pr_123'}"
```

--------------------------------

### Upload with custom artifact path

Source: https://docs.reccehq.com/setup-guides/setup-ci

Use this command when dbt artifacts are stored in a non-standard directory.

```bash
recce-cloud upload --target-path custom-target
```

--------------------------------

### Configure DuckDB Profile

Source: https://docs.reccehq.com/getting-started/jaffle-shop-tutorial

Define the prod and dev targets in the profiles.yml file.

```yaml
    prod:
      type: duckdb
      path: 'jaffle_shop.duckdb'
      schema: prod
      threads: 24
```

```yaml
jaffle_shop:
  target: dev
  outputs:
    dev:
      type: duckdb
      path: 'jaffle_shop.duckdb'
      threads: 24
    prod:
      type: duckdb
      path: 'jaffle_shop.duckdb'
      schema: prod
      threads: 24
```

--------------------------------

### Configure CI for Optimized Session Base

Source: https://docs.reccehq.com/setup-guides/environment-advanced

Suitable for large projects, this configuration utilizes dbt clone, selective rebuilds, and data sampling to reduce CI execution time.

```yaml
env:
  PR_BRANCH: ${{ github.head_ref }}

steps:
  - name: Fetch production artifacts
    run: |
      mkdir -p prod_artifacts/
      aws s3 cp s3://your-bucket/dbt-artifacts/manifest.json prod_artifacts/

  - name: Build Session Base (clone + selective rebuild)
    run: |
      MERGE_BASE=$(git merge-base origin/main ${{ env.PR_BRANCH }})
      git checkout $MERGE_BASE
      dbt clone --target pr_base --state prod_artifacts/
      # Adjust dates to match your data range
      dbt build --target pr_base --select tag:environment_dependent \
        --sample="{'start': '2025-02-01', 'end': '2025-02-28'}"
      dbt docs generate --target pr_base

  - name: Upload Session Base Artifacts to Recce Cloud
    run: recce-cloud upload --session-base
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

  - name: Build PR Current
    run: |
      git checkout ${{ env.PR_BRANCH }}
      # Use the same date range as session base
      dbt build --target pr_current \
        --sample="{'start': '2025-02-01', 'end': '2025-02-28'}"
      dbt docs generate --target pr_current

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

--------------------------------

### Execute dbt Slim CI Build

Source: https://docs.reccehq.com/setup-guides/environment-best-practices

Runs dbt build on modified models and their downstream dependencies using production artifacts for deferral.

```bash
dbt build --select state:modified+ --defer --state prod-artifacts/
```

--------------------------------

### Execute Recce Checks

Source: https://docs.reccehq.com/using-recce/cli-commands

Run preset checks and save the results to a state file.

```bash
recce run [OPTIONS]
```

--------------------------------

### Generate Recce Summary

Source: https://docs.reccehq.com/using-recce/cli-commands

Create a summary report from a specified state file.

```bash
recce summary <STATE_FILE>
```

--------------------------------

### Download dbt Cloud Artifacts

Source: https://docs.reccehq.com/getting-started/oss-setup

Use the dbt Cloud API to download production artifacts when working in a CI/CD environment.

```shell
# Set your dbt Cloud credentials
export DBT_CLOUD_API_TOKEN="your-token"
export DBT_CLOUD_ACCOUNT_ID="your-account-id"
export DBT_CLOUD_JOB_ID="your-production-job-id"

# Download artifacts from your production job
curl -H "Authorization: Token $DBT_CLOUD_API_TOKEN" \
  "https://cloud.getdbt.com/api/v2/accounts/$DBT_CLOUD_ACCOUNT_ID/jobs/$DBT_CLOUD_JOB_ID/artifacts/manifest.json" \
  -o target-base/manifest.json

curl -H "Authorization: Token $DBT_CLOUD_API_TOKEN" \
  "https://cloud.getdbt.com/api/v2/accounts/$DBT_CLOUD_ACCOUNT_ID/jobs/$DBT_CLOUD_JOB_ID/artifacts/catalog.json" \
  -o target-base/catalog.json
```

--------------------------------

### Generic MCP Configuration

Source: https://docs.reccehq.com/setup-guides/mcp-server

Standard configuration formats for generic MCP clients.

```json
{
  "command": "recce",
  "args": ["mcp-server"],
  "transport": "stdio"
}
```

```shell
recce mcp-server --sse --host localhost --port 8000
```

--------------------------------

### Configure CI for Session Base with Full Rebuild

Source: https://docs.reccehq.com/setup-guides/environment-advanced

Use this configuration for smaller projects where environment-dependent SQL requires a full rebuild of the session base and current PR state.

```yaml
env:
  PR_BRANCH: ${{ github.head_ref }}

steps:
  - name: Build Session Base (from merge base)
    run: |
      MERGE_BASE=$(git merge-base origin/main ${{ env.PR_BRANCH }})
      git checkout $MERGE_BASE
      dbt build --target pr_base
      dbt docs generate --target pr_base

  - name: Upload Session Base Artifacts to Recce Cloud
    run: recce-cloud upload --session-base
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

  - name: Build PR Current
    run: |
      git checkout ${{ env.PR_BRANCH }}
      dbt build --target pr_current
      dbt docs generate --target pr_current

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

--------------------------------

### Configure Windsurf MCP

Source: https://docs.reccehq.com/setup-guides/mcp-server

Add Recce configuration to the Windsurf MCP settings file.

```json
{
  "mcpServers": {
    "recce": {
      "command": "recce",
      "args": ["mcp-server"]
    }
  }
}
```

--------------------------------

### Add Recce marketplace

Source: https://docs.reccehq.com/setup-guides/claude-plugin

Register the Recce plugin repository in Claude Code.

```text
/plugin marketplace add DataRecce/recce-claude-plugin
```

--------------------------------

### Configure Cloud Connection

Source: https://docs.reccehq.com/collaboration/share

Methods for manually configuring the cloud connection using an API token.

```bash
recce server --api-token <your_api_token>
```

```yaml
api_token: <your_api_token>
```

--------------------------------

### Configure GitHub Actions for dbt Cloud CI

Source: https://docs.reccehq.com/setup-guides/dbt-cloud-setup

Defines a workflow to wait for a dbt Cloud CI job, download artifacts, and upload them to Recce Cloud. Requires secrets for DBT_CLOUD_ACCOUNT_ID, DBT_CLOUD_API_TOKEN, and DBT_CLOUD_CI_JOB_ID.

```yaml
name: Validate PR (dbt Cloud)

on:
  pull_request:
    branches: [main]

env:
  DBT_CLOUD_API_BASE: "https://cloud.getdbt.com/api/v2/accounts/${{ secrets.DBT_CLOUD_ACCOUNT_ID }}"
  DBT_CLOUD_API_TOKEN: ${{ secrets.DBT_CLOUD_API_TOKEN }}

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

      - uses: actions/setup-python@v5
        with:
          python-version: "3.10"

      - name: Install recce-cloud
        run: pip install recce-cloud

      - name: Wait for dbt Cloud CI job
        env:
          DBT_CLOUD_CI_JOB_ID: ${{ secrets.DBT_CLOUD_CI_JOB_ID }}
          CURRENT_GITHUB_SHA: ${{ github.event.pull_request.head.sha }}
        run: |
          set -eo pipefail
          CI_RUNS_URL="${DBT_CLOUD_API_BASE}/runs/?job_definition_id=${DBT_CLOUD_CI_JOB_ID}&order_by=-id"
          fetch_ci_run_id() {
            CI_RUNS_RESPONSE=$(curl -sSf -H "Authorization: Bearer ${DBT_CLOUD_API_TOKEN}" "${CI_RUNS_URL}")
            echo "${CI_RUNS_RESPONSE}" | jq -r ".data[] | select(.git_sha == \"${CURRENT_GITHUB_SHA}\") | .id" | head -n1
          }
          DBT_CLOUD_CI_RUN_ID=$(fetch_ci_run_id)
          while [ -z "$DBT_CLOUD_CI_RUN_ID" ]; do
            echo "Waiting for dbt Cloud CI job to start..."
            sleep 10
            DBT_CLOUD_CI_RUN_ID=$(fetch_ci_run_id)
          done
          echo "DBT_CLOUD_CI_RUN_ID=${DBT_CLOUD_CI_RUN_ID}" >> $GITHUB_ENV
          CI_RUN_URL="${DBT_CLOUD_API_BASE}/runs/${DBT_CLOUD_CI_RUN_ID}/"
          while true; do
            CI_RUN_RESPONSE=$(curl -sSf -H "Authorization: Bearer ${DBT_CLOUD_API_TOKEN}" "${CI_RUN_URL}")
            CI_RUN_SUCCESS=$(echo "${CI_RUN_RESPONSE}" | jq '.data.is_complete and .data.is_success')
            CI_RUN_FAILED=$(echo "${CI_RUN_RESPONSE}" | jq '.data.is_complete and (.data.is_error or .data.is_cancelled)')
            if $CI_RUN_SUCCESS; then
              echo "dbt Cloud CI job completed successfully."
              break
            elif $CI_RUN_FAILED; then
              status=$(echo ${CI_RUN_RESPONSE} | jq -r '.data.status_humanized')
              echo "dbt Cloud CI job failed or was cancelled. Status: $status"
              exit 1
            fi
            echo "Waiting for dbt Cloud CI job to complete..."
            sleep 10
          done

      - name: Retrieve artifacts from CI job
        run: |
          set -eo pipefail
          mkdir -p target
          for artifact in manifest.json catalog.json; do
            ARTIFACT_URL="${DBT_CLOUD_API_BASE}/runs/${DBT_CLOUD_CI_RUN_ID}/artifacts/${artifact}"
            curl -sSf -H "Authorization: Bearer ${DBT_CLOUD_API_TOKEN}" "${ARTIFACT_URL}" -o "target/${artifact}"
          done

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