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

Authenticate - Login to your organization
Set Project - Choose which project you're working on
Generate Config - Convert config.yaml to config.py with auto-refreshing credentials
Use SQLMesh - Run SQLMesh commands normally

Authentication

dagctl auth login --org your-org

Opens your browser for OAuth authentication (Authorization Code with PKCE). Stores JWT tokens in ~/.dagctl/.

Option	Description
`--org`	Organization name or ID (required)
`--api-url`	API URL override (default: `https://api.dagctl.io`)
`-k`, `--insecure`	Skip SSL certificate verification (for dev environments)

Logout

dagctl auth logout

Clears stored JWT tokens and cached credentials from ~/.dagctl/.

Status

dagctl auth status

Shows current authentication state: whether you're authenticated, your organization, active project, credential expiry, and API URL.

Project Context

dagctl use-project my-project

Sets the active project. Verifies the project exists in your organization before saving. After setting the project, run dagctl config generate to create your SQLMesh config.

Option	Description
`-k`, `--insecure`	Skip SSL certificate verification

Configuration

Generate Config

dagctl config generate

Reads your existing config.yaml and converts it to a config.py that uses dagctl's get_state_connection() for auto-refreshing credentials. The original config.yaml is backed up as config.yaml.bak.

Option	Description
`-o`, `--output`	Output file (default: `config.py`)

The generated config.py is written with 0600 permissions and includes auto-refreshing state connection credentials, so you never need to manually rotate database passwords.

View Current Context

dagctl config current

Shows your current organization, project, credential expiry, API URL, and PG proxy endpoint.

State Connection

Once authenticated and a project is set, use get_state_connection() in your SQLMesh config to connect 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(
                gateway="my_gateway",
                default_environment="dev",
            ),
        }
    }
)

`get_state_connection()` Parameters

Parameter	Type	Default	Description
`gateway`	`str`	`None`	Gateway name. Defaults to current project context.
`default_environment`	`str`	`None`	Fallback environment for protection checks if none appears on the command line. Should match your SQLMesh config's `default_target_environment`.
`insecure`	`bool`	`False`	Skip SSL verification for dev environments with self-signed certs.

The function handles:

JWT token auto-refresh (refreshes when token expires or within 5 minutes of expiry)
Environment protection checks (blocks access to protected environments)
Connection credential computation (no separate API call needed)

Environment Protection

The CLI enforces environment protection checks automatically when you call get_state_connection(). If you manage your own state connection, you can call check_environment_protection() directly:

from dagctl import check_environment_protection

check_environment_protection(
    environment="prod",
    project_id="your-project-id",
)

`check_environment_protection()` Parameters

Parameter	Type	Default	Description
`environment`	`str`	`None`	Environment name (e.g., `prod`). If not provided, parsed from `sys.argv` (e.g., `sqlmesh plan prod`).
`default_environment`	`str`	`None`	Fallback environment if not specified on command line.
`project_id`	`str`	`None`	Project ID. Uses current project from config if not provided.
`insecure`	`bool`	`False`	Skip SSL verification.

The function fails closed: if it cannot reach the API to verify protection status (network error, SSL error), it blocks execution rather than allowing access.

Configuration Directory

dagctl stores configuration in ~/.dagctl/:

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