Skip to content

CLI Overview

SQLMesh users only

The dagctl CLI is used to connect your local SQLMesh environment to the dagctl-managed state database. dbt projects are managed entirely through the web UI and do not require the CLI.

The dagctl CLI connects your local SQLMesh projects to the dagctl platform.

Installation

pip install dagctl

Basic Workflow

  1. Authenticate - Login to your organization
  2. Set Project - Choose which project you're working on
  3. Use SQLMesh - Run SQLMesh commands normally

Authentication

dagctl auth login --org your-org

Opens your browser for OAuth authentication. Stores JWT tokens in ~/.dagctl/.

Project Context

dagctl use-project my-project

Sets the active project. SQLMesh will use this project's state database.

State Connection

Once authenticated and a project is set, SQLMesh automatically connects to the dagctl state database:

from dagctl import get_state_connection
from sqlmesh.core.config import Config

config = Config(
    gateways={
        "my_gateway": {
            "connection": {...},
            "state_connection": get_state_connection(),
        }
    }
)

The CLI handles:

  • JWT token refresh
  • Connection details
  • Database credentials

Configuration

dagctl stores configuration in ~/.dagctl/:

~/.dagctl/
├── config.yaml      # Current org/project
└── auth.json        # JWT tokens (0600 permissions)