[!NOTE] dbt-cloud-cli wraps the dbt Cloud REST API. It is not the same as the dbt Cloud CLI, which runs dbt commands against a Cloud development environment.

dbt-cloud-cli

A command-line interface and Python library for the dbt Cloud API. Use it to trigger jobs, manage resources, and download run artifacts from a terminal, a CI/CD pipeline, or an AI agent.

Quick start

pip install dbt-cloud-cli

export DBT_CLOUD_API_TOKEN=<your token>
export DBT_CLOUD_ACCOUNT_ID=<your account id>

# Trigger a job and wait for it to finish
dbt-cloud job run --job-id 43167 --cause "Triggered from CLI" --wait

Output (status messages go to stderr, JSON response to stdout):

Job 43167 run 34929305: QUEUED ...
Job 43167 run 34929305: RUNNING ...
Job 43167 run 34929305: SUCCESS ...
{"status": {"code": 200, ...}, "data": {"id": 34929305, ...}}

Installation

Requires Python 3.8+.

pip install dbt-cloud-cli

Docker:

docker run datamie/dbt-cloud-cli:latest

Configuration

Set these environment variables to avoid repeating flags on every command:

Use cases

• CI/CD pipelines: Trigger a job on every PR merge and fail the pipeline if it errors
• Job management: Create, copy, and delete jobs across dbt Cloud projects with job export / job import
• Artifact downloads: Pull manifest.json, run_results.json, or catalog.json after a run
• AI agents: Use the Python library interface to give an LLM agent access to dbt Cloud operations

Using as a Python library (for AI agents)

dbt-cloud-cli ships pre-built tool definitions for OpenAI function calling and Anthropic tool use, generated directly from the same Pydantic models that power the CLI.

from dbt_cloud.tools import get_openai_tools, get_anthropic_tools, execute_tool_call
import os

os.environ["DBT_CLOUD_API_TOKEN"] = "<your token>"
os.environ["DBT_CLOUD_ACCOUNT_ID"] = "123456"  # or set per call

OpenAI

import openai
from dbt_cloud.tools import get_openai_tools, execute_tool_call

client = openai.OpenAI()
tools = get_openai_tools()  # or get_openai_tools(include=["job_run", "run_get"])

messages = [{"role": "user", "content": "Run job 43167 and tell me if it succeeded."}]
response = client.chat.completions.create(model="gpt-4o", tools=tools, messages=messages)

for tool_call in response.choices[0].message.tool_calls or []:
    result = execute_tool_call(tool_call.function.name, json.loads(tool_call.function.arguments))
    messages.append({"role": "tool", "tool_call_id": tool_call.id, "content": json.dumps(result)})

Anthropic

import anthropic
from dbt_cloud.tools import get_anthropic_tools, execute_tool_call

client = anthropic.Anthropic()
tools = get_anthropic_tools()  # or get_anthropic_tools(include=["job_run", "run_get"])

response = client.messages.create(
    model="claude-opus-4-6",
    tools=tools,
    messages=[{"role": "user", "content": "Run job 43167 and tell me if it succeeded."}],
)

for block in response.content:
    if block.type == "tool_use":
        result = execute_tool_call(block.name, block.input)
        # append tool_result to messages and continue the loop

Direct execution (no LLM)

from dbt_cloud.tools import execute_tool_call

result = execute_tool_call("job_run", {"account_id": 123456, "job_id": 43167, "cause": "nightly"})
print(result["data"]["id"])  # run ID

Available tools

All 27 tools are available. Use include to expose only what the agent needs:

# Read-only agent — can inspect but not mutate
tools = get_anthropic_tools(include=[
    "job_get", "job_list",
    "run_get", "run_list", "run_list_artifacts", "run_get_artifact",
    "project_get", "project_list",
    "environment_get", "environment_list",
])

For headless/production deployments, set DBT_CLOUD_READONLY=true to enforce this at the environment level.

Commands

For full argument reference, run dbt-cloud <command> --help.

Command reference

dbt-cloud account get

Retrieves dbt Cloud account information.

dbt-cloud account get --account-id 123456

Sample response

dbt-cloud account list

Lists all dbt Cloud accounts accessible with the current API token.

dbt-cloud account list

Sample response

dbt-cloud audit-log get

Enterprise accounts only.

Retrieves audit logs for a dbt Cloud account.

dbt-cloud audit-log get --logged-at-start 2022-05-01 --logged-at-end 2022-05-07 --limit 1

Sample response

dbt-cloud project create

Creates a new dbt Cloud project.

dbt-cloud project create --name "My project" --type 0

Sample response

dbt-cloud project delete

Deletes a dbt Cloud project.

dbt-cloud project delete --project-id 273731

Sample response

dbt-cloud project get

Retrieves dbt Cloud project details.

dbt-cloud project get --project-id 123457

Sample response

dbt-cloud project list

Lists all projects in an account.

dbt-cloud project list

Sample response

dbt-cloud project update

Updates a project.

dbt-cloud project update --project-id 273745 --name "My project renamed"

Sample response

dbt-cloud environment create

Creates a new environment in a dbt Cloud project.

dbt-cloud environment create --project-id 123457 --name "Production" --type deployment --dbt-version "1.8.0-latest"

Sample response

dbt-cloud environment delete

Deletes an environment.

dbt-cloud environment delete --project-id 123457 --environment-id 40480

Sample response

dbt-cloud environment get

Retrieves details of an environment.

dbt-cloud environment get --project-id 123457 --environment-id 67890

Sample response

dbt-cloud environment list

Lists environments in a project.

dbt-cloud environment list --project-id 123457

Sample response

dbt-cloud connection create

Creates a database connection in a project. Supported types: snowflake, bigquery, postgres, redshift, adapter.

dbt-cloud connection create \
  --project-id 123467 \
  --name Snowflake \
  --type snowflake \
  --account snowflake_account \
  --database analytics \
  --warehouse transforming \
  --role transformer \
  --allow-sso False \
  --client-session-keep-alive False

Sample response

dbt-cloud connection delete

Deletes a database connection.

dbt-cloud connection delete --project-id 123467 --connection-id 56901

Sample response

dbt-cloud connection get

Retrieves details of a database connection.

dbt-cloud connection get --project-id 123467 --connection-id 56901

Sample response

dbt-cloud connection list

Lists database connections in a project.

dbt-cloud connection list --project-id 123467

Sample response

dbt-cloud job run

Triggers a dbt Cloud job run. Use --wait to poll until completion.

dbt-cloud job run --job-id 43167 --cause "My first run!" --wait

# Override steps for this run only
dbt-cloud job run --job-id 43167 --steps-override '["dbt seed", "dbt run"]' --wait

Sample response

dbt-cloud job get

Returns details of a dbt Cloud job.

dbt-cloud job get --job-id 43167

Sample response

dbt-cloud job list

Lists jobs in an account.

dbt-cloud job list --project-id 123457 --limit 20

Sample response

dbt-cloud job create

Creates a job in a dbt Cloud project.

dbt-cloud job create \
  --project-id 12345 \
  --environment-id 49819 \
  --name "Nightly run" \
  --execute-steps '["dbt seed", "dbt run", "dbt test"]' \
  --job-type scheduled

Sample response

dbt-cloud job delete

Deletes a job.

dbt-cloud job delete --job-id 48474

Sample response

dbt-cloud job delete-all

Composite command.

Lists all jobs in the account and deletes them one-by-one with confirmation prompts. Use --keep-jobs to exclude specific job IDs, and --yes to skip prompts.

dbt-cloud job delete-all --keep-jobs "[43167, 49663]"

Jobs to delete: [54658, 54659]
Delete job 54658? [y/N]: yes
Job 54658 was deleted.
Delete job 54659? [y/N]: yes
Job 54659 was deleted.

dbt-cloud job export

Composite command.

Exports a job definition as JSON. Use with job import to copy jobs between projects.

dbt-cloud job export --job-id 43167 > job.json

dbt-cloud job import

Composite command.

Imports a job from exported JSON. Pipe through jq to modify fields before importing.

dbt-cloud job export --job-id 43167 \
  | jq '.environment_id = 49819 | .name = "Imported job"' \
  | dbt-cloud job import

dbt-cloud run get

Returns details of a run.

dbt-cloud run get --run-id 36053848

Sample response

dbt-cloud run list

Lists runs in an account.

dbt-cloud run list --limit 20

Sample response

dbt-cloud run cancel

Cancels a run. Can be sent against a run in any state (has no effect if the run has already completed).

dbt-cloud run cancel --run-id 36053848

Sample response

dbt-cloud run cancel-all

Composite command.

Cancels runs with confirmation prompts. Use --status to filter by run state (typically Running or Queued).

dbt-cloud run cancel-all --status Running

Runs to cancel: [36053848]
Cancel run 36053848? [y/N]: yes
Run 36053848 has been cancelled.

dbt-cloud run list-artifacts

Lists artifact files generated for a completed run.

dbt-cloud run list-artifacts --run-id 36053848

Sample response

dbt-cloud run get-artifact

Downloads an artifact file from a completed run. Supports manifest.json, run_results.json, catalog.json, and others.

dbt-cloud run get-artifact --run-id 36053848 --path manifest.json > manifest.json

dbt-cloud metadata query

Queries the dbt Cloud Metadata API using GraphQL.

dbt-cloud metadata query -f query.graphql

Or pipe a query directly:

echo '{
  model(jobId: 49663, uniqueId: "model.jaffle_shop.customers") {
    parentsModels { runId uniqueId executionTime }
    parentsSources { runId uniqueId state }
  }
}' | dbt-cloud metadata query

Sample query

Demo utilities

Install with the demo extra:

pip install dbt-cloud-cli[demo]

dbt-cloud demo data-catalog

An interactive CLI for exploring catalog.json artifacts.

latest_run_id=$(dbt-cloud run list --job-id $DBT_CLOUD_JOB_ID --limit 1 | jq .data[0].id -r)
dbt-cloud run get-artifact --run-id $latest_run_id --path catalog.json > catalog.json
dbt-cloud demo data-catalog -f catalog.json

Acknowledgements

Thanks to Sean McIntyre for his initial work on triggering a dbt Cloud job using Python as proposed in this post on dbt Discourse.