Skip to content

Getting Started

This guide walks you through installing the CLI, creating a project, and deploying it to a Fabric Lakehouse.

Prerequisites

  • Python 3.11+
  • Azure CLI (az) — required for deploy and status commands

Installation

uv tool install weevr-cli

pipx install weevr-cli

pip install weevr-cli

Verify the installation:

weevr --version

Create a Project

Scaffold a new project with example files:

weevr init my-project --examples

This creates a directory named my-project.weevr/ with the following structure:

my-project.weevr/
├── .weevr/
│   └── cli.yaml              # CLI configuration
├── staging/
│   └── stg_customers.thread  # Example thread
├── staging.weave             # Example weave (references the thread)
└── daily.loom                # Example loom (references the weave)

The example files form a self-consistent pipeline: the loom references the weave, and the weave references the thread. File extensions (.thread, .weave, .loom) identify the file type — no .yaml suffix is used.

Note

The .weevr suffix on the project directory is required. The weevr engine uses it to detect project roots. The CLI adds it automatically if you omit it.

Move into the project:

cd my-project.weevr

Explore the Project

View the project structure:

weevr list

See dependency relationships in table format:

weevr list --format table

Generate Files

Create new files from templates:

weevr new thread orders
weevr new weave customer_dim
weevr new loom daily_load
weevr new warp customer_schema

Each command generates a file with the standard schema fields pre-filled. Files use type-specific extensions (.thread, .weave, .loom, .warp).

Validate

Check schema conformance and cross-file reference integrity:

weevr validate

Use --strict to treat warnings as errors:

weevr validate --strict

Parameterized templates

Files that use variable references like ${param.pk_columns} or ${env.DB_NAME} pass validation even when the referenced field expects a non-string type (e.g. an array). The validator skips static type checks on bare ${...} values since they are resolved at runtime by the weevr engine.

Exclude Files From the Project

If you have scratch folders, drafts, or experiments you don't want the CLI to treat as part of the project, create a .weevr/ignore file with gitignore-style patterns:

# .weevr/ignore

# Scratch folder for in-progress work
scratch/

# Drafts
*.draft.thread
*.draft.weave

The patterns apply to every command that walks the project tree — validate, list, deploy, and status — so ignored files never show up as orphans, never fail validation, and never upload to Fabric. You can use either .weevr/ignore or a .weevrignore at the project root (the familiar gitignore-style location), or both. See Configuration › Ignore files for the full reference, including how explicit target paths bypass the filter.

Configure a Deploy Target

Edit .weevr/cli.yaml with your Fabric workspace GUID and lakehouse identifier. Use lakehouse_id (a GUID) by default; use lakehouse_name only if your tenant supports friendly-name lookup. The two are mutually exclusive — provide exactly one per target.

targets:
  dev:
    workspace_id: "your-workspace-guid"
    lakehouse_id: "your-lakehouse-guid"
    path_prefix: "weevr"

default_target: dev

The path_prefix is optional — it adds a namespace before the project folder on the Lakehouse. With this config, files deploy to Files/weevr/my-project.weevr/.... The project folder name is always included automatically.

See Configuration › Targets for the lakehouse_name alternative and the full field reference.

You can define multiple targets (e.g., dev, staging, prod) and switch between them with --target.

Authenticate

Log in with the Azure CLI:

az login

The CLI uses Azure DefaultAzureCredential, which picks up credentials from az login, environment variables, managed identities, or the VS Code Azure extension.

Deploy

Deploy your project to the Lakehouse:

weevr deploy --target dev

Preview what would change without deploying:

weevr deploy --target dev --dry-run

Tip

Your first deploy works against an empty Lakehouse — you don't need to pre-create the project folder under Files/ or run any setup on the OneLake side. The CLI prints a path=... banner showing exactly where your files will land under Files/.

Check Status

See what differs between local files and the deployed state:

weevr status

Next Steps