Using branch deployments with the dagster-cloud CLI

note

This guide is applicable to Dagster+.

The dagster-cloud CLI is a command-line toolkit designed to work with Dagster+.

In this guide, we'll cover how to install and configure the dagster-cloud CLI, get help, and use some helpful environment variables and CLI options.

Installing the CLI

The Dagster+ Agent library is available in PyPi. To install, run:

pip install dagster-cloud

Refer to the configuration section for next steps.

Completions

Optionally, you can install command-line completions to make using the dagster-cloud CLI easier.

To have the CLI install these completions to your shell, run:

dagster-cloud --install-completion

To print out the completion for copying or manual installation:

dagster-cloud --show-completion

Configuring the CLI

The recommended way to set up your CLI's config for long-term use is through the configuration file, located by default at ~/.dagster_cloud_cli/config.

Setting up the configuration file

Set up the config file:

dagster-cloud config setup

Select your authentication method. Note: Browser authentication is the easiest method to configure.

BROWSER AUTHENTICATION

The easiest way to set up is to authenticate through the browser.

$ dagster-cloud config setup
? How would you like to authenticate the CLI? (Use arrow keys)
 » Authenticate in browser
   Authenticate using token
Authorized for organization `hooli`

? Default deployment: prod

When prompted, you can specify a default deployment. If specified, a deployment won't be required in subsequent dagster-cloud commands. The default deployment for a new Dagster+ organization is prod.

TOKEN AUTHENTICATION

Alternatively, you may authenticate using a user token. Refer to the Managing user and agent tokens guide for more info.

$ dagster-cloud config setup
? How would you like to authenticate the CLI? (Use arrow keys)
   Authenticate in browser
 » Authenticate using token

? Dagster+ organization: hooli
? Dagster+ user token: *************************************
? Default deployment: prod

When prompted, specify the following:

• Organization - Your organization name as it appears in your Dagster+ URL. For example, if your Dagster+ instance is https://hooli.dagster.cloud/, this would be hooli.
• User token - The user token.
• Default deployment - Optional. A default deployment. If specified, a deployment won't be required in subsequent dagster-cloud commands. The default deployment for a new Dagster+ organization is prod.

Viewing and modifying the configuration file

To view the contents of the CLI configuration file, run:

$ dagster-cloud config view

default_deployment: prod
organization: hooli
user_token: '*******************************8214fe'

Specify the --show-token flag to show the full user token.

To modify the existing config, re-run:

dagster-cloud config setup

Toggling between deployments

To quickly toggle between deployments, run:

dagster-cloud config set-deployment <deployment_name>

Getting help

To view help options in the CLI:

dagster-cloud --help

Reference

• Custom configuration file path
• Environment variables and CLI options

Custom configuration file path

Point the CLI at an alternate config location by specifying the DAGSTER_CLOUD_CLI_CONFIG environment variable.

Environment variables and CLI options

Environment variables and CLI options can be used in place of or to override the CLI configuration file.

The priority of these items is as follows:

• CLI options - highest
• Environment variables
• CLI configuration - lowest

Setting	Environment variable	CLI flag	CLI config value
Organization	DAGSTER_CLOUD_ORGANIZATION	--organization, -o	organization
Deployment	DAGSTER_CLOUD_DEPLOYMENT	--deployment, -d	default_deployment
User Token	DAGSTER_CLOUD_API_TOKEN	--user-token, -u	user_token