Using the dagster-cloud CLI#

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

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`