CLI Reference

CLI commands

Authentication

wren auth login

Prompts for Organization ID, API Key, and optional API endpoint. Credentials are stored in ~/.wrenai/wrenrc.yaml.

wren auth status

Show current login status.

wren auth logout

Remove the saved credentials.

dbt import

Plan support

dbt integration is available on Essential / Business plans and above.

warning

Updating replaces the current MDL in your Wren AI project with those generated from your dbt models. Any manual changes made in Wren AI will be overwritten.

Create a new Wren AI project from a dbt project:

wren dbt create

With filter patterns:

# Include only marts models
wren dbt create --include "marts_.*"

# Exclude calculate models
wren dbt create --exclude "calculate_.*"

# Combine filters
wren dbt create --include "(marts|dim|fct)_.*" --exclude ".*_test"

# Preview before creating
wren dbt create --include "marts_.*" --dry-run

Update an existing linked project (referenced in .wrenconfig):

wren dbt update --dbt-path /path/to/dbt-project

Preview update with different filters (without modifying .wrenconfig):

wren dbt update --dbt-path /path/to/dbt-project --include "orders" --dry-run

Filter behavior

• Create: Filter flags save patterns to .wrenconfig
• Update: Uses filters from .wrenconfig by default
• Update with filter flags: Only allowed with --dry-run for preview

Skip confirmation:

wren dbt update --dbt-path /path/to/dbt-project --yes

Filter patterns

Filters use standard regex syntax:

Pattern	Description	Example Matches
orders	Exact match	orders
marts_.*	Prefix match	marts_revenue, marts_users
.*_staging	Suffix match	orders_staging, customers_staging
(dim|fct)_.*	Multiple prefixes	dim_customers, fct_orders
.*test.*	Contains	test_orders, orders_test

Metadata Sync

Sync table and column descriptions from YAML files to your Wren AI project.

wren metadata sync --config /path/to/config-file.yaml

Or use interactive mode:

wren metadata sync --project-id <project-id> 

Skip confirmation:

wren metadata sync --config /path/to/config-file.yaml  --yes 

---

dbt project Configuration files

.wrenconfig (project-level)

Created by wren dbt create in the root of your dbt project. Used by wren dbt update to locate and update the linked Wren AI project.

Typical contents:

# .wrenconfig
wren_project:
  id: "783" # Wren AI Cloud Project ID
  last_synced: "2025-12-24T10:28:07.006Z" # Last sync time

# Optional: Filter patterns for model selection
filter:
  include:
    - "marts_.*"
    - "dim_.*"
    - "fct_.*"
  exclude:
    - "staging_.*"
    - ".*_test"

Filter behavior:

• Patterns defined here are automatically applied during wren dbt update
• Filters set during wren dbt create are saved here
• To change filters, edit this file directly
• Supports multiple regex patterns per filter type

Notes:

• Commit this file to your dbt repository so collaborators can run wren dbt update.
• Filter patterns use standard regex syntax and are anchored (^pattern$)

wrenrc.yaml (user-level)

Written to ~/.wrenai/wrenrc.yaml after wren auth login. Stores your local authentication and defaults.

Typical contents:

# ~/.wrenai/wrenrc.yaml
wren_profiles:
  org_id: "5" # Your Organization ID
  apikey: osk-xxx # Your API key
  endpoint: https://cloud.getwren.ai/api/ # API endpoint

Notes:

• This file is user-specific; do not commit it.

Metadata configuration files

metadata-config.yaml

The metadata-config.yaml file defines how the wren metadata sync command scans and interprets your local YAML files to synchronize metadata (such as table and column descriptions) with your Wren AI project.

Typical contents:

# metadata-config.yaml

# Path or glob pattern to locate your metadata files.
# Can point to a single file, a directory, or use glob patterns.
file_path: "./metadata/*.yaml"

# (Optional) Limit included files when scanning a directory.
include_patterns:
  - "*.yaml"
  - "*.yml"

# (Optional) Exclude specific files or patterns.
exclude_patterns:
  - "*.backup.yaml"
  - "deprecated_*.yaml"

# Wren AI target project to sync with.
target_project_id: "123"

# Mapping rules for how metadata is extracted from YAML files.
description_property_name: "purpose"         # Field for table description
columns_property_name: "columns"             # Field listing columns
column_description_property_name: "description"  # Field for column descriptions

table_name_property: "metadata.schema_name"

Example metadata YAML (referenced by metadata-config.yaml)

# customers.yaml
metadata:
  schema_name: test.customers
  purpose: Customer data table

columns:
  - name: customer_id
    type: string
    description: "Unique customer identifier."

  - name: customer_name
    type: string
    description: "Customer’s full name."
  
  - name: customer_address
    type: string
    description: Customer address

TL;DR Using the above metadata-config.yaml and customers.yaml as an example:

the CLI will:

• Scan all files matching ./metadata/*.yaml.
• Read the example file (customers.yaml) that matches the glob pattern.
• Extract table name from metadata.schema_name (as defined by table_name_property in metadata-config.yaml) → test.customers.
• Read table description from the purpose (as defined by description_property_name in metadata-config.yaml) field → "Customer data table".
• Find columns under the columns(as defined by columns_property_name in metadata-config.yaml) list.
• For each column, map the description(as defined by column_description_property_name in metadata-config.yaml) field as the column description (e.g., "Unique customer identifier.").