Package: dbt-cloud-cli
dbt-cloud-clidbt-cloud-cliis a command line interface fordbt Cloud API. It abstracts the REST API calls in an easy-to-use interface that can be incorporated into automated and manual (ad-hoc) workloads. Here are some example use cases fordbt-cloud-cli:Triggering a dbt Cloud job to run in a CI/CD pipeline: Usedbt-cloud job runin a CI/CD workflow (e.g., Github Actions) to trigger a dbt Cloud job that runs and tests the changes in a commit branchSetting up dbt Cloud jobs: Usedbt-cloud job createto create standardized jobs between dbt Cloud projects. You can also usedbt-cloud job exportto export an existing job from one dbt Cloud project and thendbt-cloud job importto import it to another.Downloading run artifacts: Usedbt-cloud run get-artifactto download run artifacts (e.g.,catalog.json) from dbt Cloud.Retrieving metadata: Usedbt-cloud metadata queryto retrieve metadata (e.g., model execution times, test results) from a dbt Cloud project.Installationdbt-cloud-clihas been tested with the following Python versions:✅ Python 3.6✅ Python 3.7✅ Python 3.8✅ Python 3.9✅ Python 3.10Installation from PyPI:pipinstalldbt-cloud-cliRunning in Docker:dockerrundatamie/dbt-cloud-cli:latestEnvironment variablesThe following environment variables are used as argument defaults:DBT_CLOUD_HOST(--dbt-cloud-host): dbt Cloud host (cloud.getdbt.com(multi-tenant instance) by default if the environment variable is not set)DBT_CLOUD_API_TOKEN(--api-token): API authentication keyDBT_CLOUD_ACCOUNT_ID(--account-id): Numeric ID of the dbt Cloud accountDBT_CLOUD_JOB_ID(--job-id): Numeric ID of a dbt Cloud jobCommandsFor more information on a command, rundbt-cloud <command> --help. For more information on the API endpoints, seedbt Cloud API V3 docsanddbt Cloud Metadata API docs.GroupCommandImplementedAPI endpointAccountdbt-cloud account get✅GEThttps://{dbt_cloud_host}/api/v2/accounts/{account_id}/Accountdbt-cloud account list✅GEThttps://{dbt_cloud_host}/api/v3/accounts/Audit logdbt-cloud audit-log get✅GEThttps://{dbt_cloud_host}/api/v3/audit-logs/Projectdbt-cloud project create✅POSThttps://{dbt_cloud_host}/api/v3/accounts/{account_id}/projects/Projectdbt-cloud project delete✅DELETEhttps://{dbt_cloud_host}/api/v3/accounts/{account_id}/projects/{id}/Projectdbt-cloud project get✅GEThttps://{dbt_cloud_host}/api/v3/accounts/{account_id}/projects/{id}/Projectdbt-cloud project list✅GEThttps://{dbt_cloud_host}/api/v3/accounts/{account_id}/projects/Projectdbt-cloud project update✅POSThttps://{dbt_cloud_host}/api/v3/accounts/{account_id}/projects/{id}/Environmentdbt-cloud environment create✅POSThttps://{dbt_cloud_host}/api/v3/accounts/{account_id}/environments/Environmentdbt-cloud environment delete✅DELETEhttps://{dbt_cloud_host}/api/v3/accounts/{account_id}/environments/{id}/Environmentdbt-cloud environment get✅GEThttps://{dbt_cloud_host}/api/v3/accounts/{account_id}/environments/{id}/Environmentdbt-cloud environment list✅GEThttps://{dbt_cloud_host}/api/v3/accounts/{account_id}/environments/Environmentdbt-cloud environment update❌POSThttps://{dbt_cloud_host}/api/v3/accounts/{account_id}/environments/{id}/Connectiondbt-cloud connection create✅POSThttps://{dbt_cloud_host}/api/v3/accounts/{account_id}/projects/{project_id}/connections/Connectiondbt-cloud connection delete✅DELETEhttps://{dbt_cloud_host}/api/v3/accounts/{account_id}/projects/{project_id}/connections/{id}/Connectiondbt-cloud connection get✅GEThttps://{dbt_cloud_host}/api/v3/accounts/{account_id}/projects/{project_id}/connections/{id}/Connectiondbt-cloud connection list✅GEThttps://{dbt_cloud_host}/api/v3/accounts/{account_id}/projects/{project_id}/connections/Connectiondbt-cloud connection update❌POSThttps://{dbt_cloud_host}/api/v3/accounts/{account_id}/projects/{project_id}/connections/{id}/Repositorydbt-cloud repository create❌POSThttps://{dbt_cloud_host}/api/v2/accounts/{account_id}/repositories/Repositorydbt-cloud repository delete❌DELETEhttps://{dbt_cloud_host}/api/v2/accounts/{account_id}/repositories/{id}/Repositorydbt-cloud repository get❌GEThttps://{dbt_cloud_host}/api/v2/accounts/{account_id}/repositories/{id}/Repositorydbt-cloud repository list❌GEThttps://{dbt_cloud_host}/api/v2/accounts/{account_id}/repositories/Jobdbt-cloud job create✅POSThttps://{dbt_cloud_host}/api/v2/accounts/{account_id}/jobs/Jobdbt-cloud job delete✅DELETEhttps://{dbt_cloud_host}/api/v2/accounts/{account_id}/jobs/{id}/Jobdbt-cloud job delete-all✅Uses a composition of one or more endpointsJobdbt-cloud job get✅GEThttps://{dbt_cloud_host}/api/v2/accounts/{account_id}/jobs/{id}/Jobdbt-cloud job list✅GEThttps://{dbt_cloud_host}/api/v2/accounts/{account_id}/jobs/Jobdbt-cloud job run✅POSThttps://{dbt_cloud_host}/api/v2/accounts/{account_id}/jobs/{job_id}/run/Jobdbt-cloud job update❌POSThttps://{dbt_cloud_host}/api/v2/accounts/{account_id}/jobs/{id}/Jobdbt-cloud job get-artifact❌GEThttps://{dbt_cloud_host}/api/v2/accounts/{account_id}/jobs/{job_id}/artifacts/{remainder}Jobdbt-cloud job export✅Uses a composition of one or more endpointsJobdbt-cloud job import✅Uses a composition of one or more endpointsRundbt-cloud run get✅GEThttps://{dbt_cloud_host}/api/v2/accounts/{account_id}/runs/{id}/Rundbt-cloud run list✅GEThttps://{dbt_cloud_host}/api/v2/accounts/{account_id}/runs/Rundbt-cloud run cancel✅POSThttps://{dbt_cloud_host}/api/v2/accounts/{account_id}/runs/{run_id}/cancel/Rundbt-cloud run cancel-all✅Uses a composition of one or more endpointsRundbt-cloud run list-artifacts✅GEThttps://{dbt_cloud_host}/api/v2/accounts/{account_id}/runs/{run_id}/artifacts/Rundbt-cloud run get-artifact✅GEThttps://{dbt_cloud_host}/api/v2/accounts/{account_id}/runs/{run_id}/artifacts/{remainder}Rundbt-cloud run get-step❌GEThttps://{dbt_cloud_host}/api/v2/accounts/{account_id}/steps/{id}/Userdbt-cloud user get❌GEThttps://{dbt_cloud_host}/api/v2/accounts/{account_id}/users/{id}/Userdbt-cloud user list❌GEThttps://{dbt_cloud_host}/api/v2/accounts/{account_id}/users/Userdbt-cloud user update❌POSThttps://{dbt_cloud_host}/api/v2/accounts/{account_id}/users/{id}/Metadatadbt-cloud metadata query✅POSThttps://{dbt_cloud_host}/graphql/dbt-cloud account getThis command retrieves dbt Cloud account information.Usagedbt-cloudaccountget--account-id123456Click to view sample responsedbt-cloud account listThis command retrieves all available dbt Cloud accounts.Usagedbt-cloudaccountlistClick to view sample responsedbt-cloud audit-log get❗Available for Enterprise accounts only.This command retrieves audit logs for the dbt Cloud account.Usagedbt-cloudaudit-logget--logged-at-start2022-05-01--logged-at-end2022-05-07--limit1Click to view sample responsedbt-cloud project createThis command creates a new dbt Cloud project in a given account.Usagedbt-cloudprojectcreate--name"My project"Click to view sample responsedbt-cloud project deleteThis command deletes a dbt Cloud project in a given account.Usagedbt-cloudprojectdelete--project-id273731Click to view sample responsedbt-cloud project getThis command retrieves dbt Cloud project information.Usagedbt-cloudprojectget--project-id123457Click to view sample responsedbt-cloud project listThis command returns a list of projects in the account.Usagedbt-cloudprojectlistClick to view sample responsedbt-cloud project updateThis command updates a project in a given account.Usagedbt-cloudprojectupdate--project-id273745--name"My project renamed"Click to view sample responsedbt-cloud environment createThis command a new dbt Cloud environment in a given project.Usagedbt-cloudenvironmentcreate--account-id123456--project-id123457--name"My environment"--dbt-version"1.5.0-latest"Click to view sample responsedbt-cloud environment deleteThis command deletes a dbt Cloud environment in a given project.Usagedbt-cloudenvironmentdelete--account-id123456--project-id123457--environment-id40480Click to view sample responsedbt-cloud environment listThis command retrieves environments in a given project.Usagedbt-cloudenvironmentlist--account-id123456--project-id123457--limit1Click to view sample responsedbt-cloud environment getThis command retrieves information about an environment in a given project.Usagedbt-cloudenvironmentget--account-id123456--project-id123457--environment-id67890Click to view sample responsedbt-cloud connection createThis command creates a new database connection in a given project. Supported connection types:snowflake: Connection to a Snowflake database. Has inout validation for connection parameters.bigquery: Connection to a Google BigQuery database. No input validation.postgres: Connection to a PostgreSQL database. No input validation.redshift: Connection to an Amazon Redshift database. No input validation.adapter: Connection to a database using a custom dbt Cloud adapter. No input validation.Usagedbt-cloudconnectioncreate--account-id54321--project-id123467--nameSnowflake--typesnowflake--accountsnowflake_account--databaseanalytics--warehousetransforming--roletransformer--allow-ssoFalse--client-session-keep-aliveFalseClick to view sample responsedbt-cloud connection deleteThis command deletes a database connection in a given project.Usagedbt-cloudconnectiondelete--account-id54321--project-id123467--connection-id56901Click to view sample responsedbt-cloud connection listThis command retrievies details of dbt Cloud database connections in a given project.Usagedbt-cloudconnectionlist--account-id54321--project-id123467--limit1Click to view sample responsedbt-cloud connection getThis command retrievies the details of a dbt Cloud database connection.Usagedbt-cloudconnectionget--account-id54321--project-id123467--connection-id56901Click to view sample responsedbt-cloud job runThis command triggers a dbt Cloud job run and returns a run status JSON response.Usage>>dbt-cloudjobrun--job-id43167--cause"My first run!"--steps-override'["dbt seed", "dbt run"]'--wait
Job43167run34929305:QUEUED...
Job43167run34929305:QUEUED...
Job43167run34929305:QUEUED...
Job43167run34929305:STARTING...
Job43167run34929305:RUNNING...
Job43167run34929305:SUCCESS...Click to view sample responsedbt-cloud job getThis command returns the details of a dbt Cloud job.Usagedbt-cloudjobget--job-id43167Click to view sample responsedbt-cloud job listThis command returns a list of jobs in the account.Usagedbt-cloudjoblist--account-id123456--project-id123457--limit2Click to view sample responsedbt-cloud job createThis command creates a job in a dbt Cloud project.Usagedbt-cloudjobcreate--project-id12345--environment-id49819--name"Create job"--execute-steps'["dbt seed", "dbt run"]'Click to view sample responsedbt-cloud job deleteThis command deletes a job in a dbt Cloud project.Usagedbt-cloudjobdelete--job-id48474Click to view sample responsedbt-cloud job delete-all💡This is a composition of one or more base commands.This command fetches all jobs on the account, deletes them one-by-one after user confirmation via prompt and prints out the job delete responses.Usage>>dbt-cloudjobdelete-all--keep-jobs"[43167, 49663]"Jobstodelete:[54658,54659]Deletejob54658?[y/N]:yes
Job54658wasdeleted.
Deletejob54659?[y/N]:yes
Job54659wasdeleted.dbt-cloud job export💡This is a composition of one or more base commands.This command exports a dbt Cloud job as JSON to a file and can be used in conjunction withdbt-cloud job importto copy jobs between dbt Cloud projects.Usagedbt-cloudjobexport>job.jsondbt-cloud job import💡This is a composition of one or more base commands.This command imports a dbt Cloud job from exported JSON. You can use JSON manipulation tools (e.g.,jq) to modify the job definition before importing it.Usagedbt-cloudjobexport>job.json
catjob.json|jq'.environment_id = 49819 | .name = "Imported job"'|dbt-cloudjobimportdbt-cloud run getThis command returns the details of a dbt Cloud run.Usagedbt-cloudrunget--run-id36053848Click to view sample responsedbt-cloud run listThis command returns a list of runs in the account.Usagedbt-cloudrunlist--limit2Click to view sample responsedbt-cloud run cancelThis command cancels a dbt Cloud run. A run can be 'cancelled' irregardless of it's previous status. This means that you can send a request to cancel a previously successful / errored run (and nothing happens practically) and the response status would be similar to cancelling a currently queued or running run.Usagedbt-cloudruncancel--run-id36053848Click to view sample responsedbt-cloud run cancel-all💡This is a composition of one or more base commands.This command fetches all runs on the account, cancels them one-by-one after user confirmation via prompt and prints out the run cancellation responses.You should typically use this with a--statusarg of eitherRunningorQueuedas cancellations can be requested against all runs. Without this, you will effectively be trying to cancel all runs that had ever been scheduled in the project irregardless of its' current status (which could take a long time if your project has had a lot of previous runs).Usage>>dbt-cloudruncancel-all--statusRunning
Runstocancel:[36053848]Cancelrun36053848?[y/N]:yes
Run36053848hasbeencancelled.dbt-cloud run list-artifactsThis command fetches a list of artifact files generated for a completed run.Usagedbt-cloudrunlist-artifacts--run-id36053848Click to view sample responsedbt-cloud run get-artifactThis command fetches an artifact file from a completed run. Once a run has completed, you can use this command to download the manifest.json, run_results.json or catalog.json files from dbt Cloud. These artifacts contain information about the models in your dbt project, timing information around their execution, and a status message indicating the result of the model build.Usagedbt-cloudrunget-artifact--run-id36053848--pathmanifest.json>manifest.jsondbt-cloud metadata queryThis command queries the dbt Cloud Metadata API using GraphQL.Usagedbt-cloudmetadataquery-fquery.graphqlClick to view sample queryAn alternative way of using the command without saving the GraphQL query to a file is to pipe it todbt-cloud metadata query.>>echo'{model(jobId: 49663, uniqueId: "model.jaffle_shop.customers") {parentsModels {runIduniqueIdexecutionTime}parentsSources {runIduniqueIdstate}}}'|dbt-cloudmetadataqueryDemo utilitiesThe utilities listed here are for demonstration purposes only and are subject to change. In order to use the demo utilities you need to install thedbt-cloud-cliwith extrademodependencies:pipinstalldbt-cloud-cli[demo]dbt-cloud demo data-catalogAn interactive CLI application for exploringcatalog.jsonartifacts.Usage>>latest_run_id=$(dbt-cloudrunlist--job-id$DBT_CLOUD_JOB_ID--limit1|jq.data[0].id-r)>>dbt-cloudrunget-artifact--run-id$latest_run_id--pathcatalog.json-fcatalog.json
>>dbt-clouddemodata-catalog-fcatalog.json#####           ##              ###           ##           ####  ##          ##             ## ##          ##           ####   ##   ###  #####   ###     ##  ##   ###  #####   ###   ##    ###    ######   ##  #  ##  ##    #  ##    ##      #  ##  ##    #  ##  ##   ## ##  ## ####  ##    ####  ##     ####   ##        ####  ##     ####  ##  ##  ##  #  ####   ##  ## ##  ##    ## ##    ##   #  ## ##  ##    ## ##  ##   ##  ## ##  ###  ##   ## ##  ##    ## ##    ##  ##  ## ##  ##    ## ##  ##   ## ##  ## #######     ## ##  ##    ## ##    ####    ## ##  ##    ## ## ##    ###    #########[?]Selectnodetypetoexplore:source>sourcenodeAcknowledgementsThanks toSean McIntyrefor his initial work on triggering a dbt Cloud job using Python as proposed inthis post on dbt Discourse. Thank you for sharing your work with the community!