dg CLI

dg check

Commands for checking the integrity of your Dagster code.

dg check [OPTIONS] COMMAND [ARGS]...

defs

Loads and validates your Dagster definitions using a Dagster instance.

If run inside a deployment directory, this command will launch all code locations in the deployment. If launched inside a code location directory, it will launch only that code location.

When running, this command sets the environment variable DAGSTER_IS_DEFS_VALIDATION_CLI=1. This environment variable can be used to control the behavior of your code in validation mode.

This command returns an exit code 1 when errors are found, otherwise an exit code 0.

dg check defs [OPTIONS]

Options:

--log-level <log_level>

Set the log level for dagster services.

Default: 'warning'Options: critical | error | warning | info | debug

--log-format <log_format>

Format of the logs for dagster services

Default: 'colored'Options: colored | json | rich

--check-yaml, --no-check-yaml: Whether to schema-check defs.yaml files for the project before loading and checking all definitions.

--target-path <target_path>: Specify a directory to use to load the context for this command. This will typically be a folder with a dg.toml or pyproject.toml file in it.

--verbose: Enable verbose output for debugging.

toml

Check TOML configuration files (dg.toml, pyproject.toml) for validity.

dg check toml [OPTIONS]

Options:

--verbose: Enable verbose output for debugging.

--target-path <target_path>: Specify a directory to use to load the context for this command. This will typically be a folder with a dg.toml or pyproject.toml file in it.

yaml

Check defs.yaml files against their schemas, showing validation errors.

dg check yaml [OPTIONS] [PATHS]...

Options:

--watch: Watch for changes to the component files and re-validate them.

--validate-requirements, --no-validate-requirements: Validate environment variables in requirements for all components in the given module.

--verbose: Enable verbose output for debugging.

--target-path <target_path>: Specify a directory to use to load the context for this command. This will typically be a folder with a dg.toml or pyproject.toml file in it.

Arguments:

PATHS: Optional argument(s)

dg dev

Start a local instance of Dagster.

If run inside a workspace directory, this command will launch all projects in the workspace. If launched inside a project directory, it will launch only that project.

dg dev [OPTIONS]

Options:

--code-server-log-level <code_server_log_level>

Set the log level for code servers spun up by dagster services.

Default: 'warning'Options: critical | error | warning | info | debug

--log-level <log_level>

Set the log level for dagster services.

Default: 'info'Options: critical | error | warning | info | debug

--log-format <log_format>

Format of the logs for dagster services

Default: 'colored'Options: colored | json | rich

-p, --port <port>: Port to use for the Dagster webserver.

-h, --host <host>: Host to use for the Dagster webserver.

--live-data-poll-rate <live_data_poll_rate>

Rate at which the dagster UI polls for updated asset data (in milliseconds)

Default: 2000

--check-yaml, --no-check-yaml: Whether to schema-check defs.yaml files for the project before starting the dev server.

--target-path <target_path>: Specify a directory to use to load the context for this command. This will typically be a folder with a dg.toml or pyproject.toml file in it.

--verbose: Enable verbose output for debugging.

--autoload-defs-module-name <autoload_defs_module_name>: A module to import and recursively search through for definitions.

-m, --module-name <module_name>: Specify module or modules (flag can be used multiple times) where dagster definitions reside as top-level symbols/variables and load each module as a code location in the current python environment.

-f, --python-file <python_file>: Specify python file or files (flag can be used multiple times) where dagster definitions reside as top-level symbols/variables and load each file as a code location in the current python environment.

-d, --working-directory <working_directory>: Specify working directory to use when loading the repository or job

-w, --workspace <workspace>: Path to workspace file. Argument can be provided multiple times.

--empty-workspace: Allow an empty workspace

Environment variables:

DAGSTER_autoload_defs_module_name: Provide a default for --autoload-defs-module-name

DAGSTER_MODULE_NAME: Provide a default for --module-name

DAGSTER_PYTHON_FILE: Provide a default for --python-file

DAGSTER_WORKING_DIRECTORY: Provide a default for --working-directory

dg launch

Launch a Dagster run.

dg launch [OPTIONS]

Options:

--assets <assets>: Comma-separated Asset selection to target

--job <job>: Job to target

--partition <partition>: Asset partition to target

--partition-range <partition_range>: Asset partition range to target i.e. <start>…<end>

--config-json <config_json>: JSON string of config to use for the launched run.

-c, --config <config>: Specify one or more run config files. These can also be file patterns. If more than one run config file is captured then those files are merged. Files listed first take precedence.

--target-path <target_path>: Specify a directory to use to load the context for this command. This will typically be a folder with a dg.toml or pyproject.toml file in it.

--verbose: Enable verbose output for debugging.

-a, --attribute <attribute>: Attribute that is either a 1) repository or job or 2) a function that returns a repository or job

--package-name <package_name>: Specify Python package where repository or job function lives

--autoload-defs-module-name <autoload_defs_module_name>: A module to import and recursively search through for definitions.

-m, --module-name <module_name>: Specify module where dagster definitions reside as top-level symbols/variables and load the module as a code location in the current python environment.

-f, --python-file <python_file>: Specify python file where dagster definitions reside as top-level symbols/variables and load the file as a code location in the current python environment.

-d, --working-directory <working_directory>: Specify working directory to use when loading the repository or job

Environment variables:

DAGSTER_ATTRIBUTE: Provide a default for --attribute

DAGSTER_PACKAGE_NAME: Provide a default for --package-name

DAGSTER_autoload_defs_module_name: Provide a default for --autoload-defs-module-name

DAGSTER_MODULE_NAME: Provide a default for --module-name

DAGSTER_PYTHON_FILE: Provide a default for --python-file

DAGSTER_WORKING_DIRECTORY: Provide a default for --working-directory

dg list

Commands for listing Dagster entities.

dg list [OPTIONS] COMMAND [ARGS]...

component-tree

dg list component-tree [OPTIONS]

Options:

--output-file <output_file>: Write to file instead of stdout. If not specified, will write to stdout.

--target-path <target_path>: Specify a directory to use to load the context for this command. This will typically be a folder with a dg.toml or pyproject.toml file in it.

--verbose: Enable verbose output for debugging.

components

List all available Dagster component types in the current Python environment.

dg list components [OPTIONS]

Options:

-p, --package <package>: Filter by package name.

--json: Output as JSON instead of a table.

--target-path <target_path>: Specify a directory to use to load the context for this command. This will typically be a folder with a dg.toml or pyproject.toml file in it.

--verbose: Enable verbose output for debugging.

defs

List registered Dagster definitions in the current project environment.

dg list defs [OPTIONS]

Options:

--json: Output as JSON instead of a table.

-p, --path <path>: Path to the definitions to list.

-a, --assets <assets>: Asset selection to list.

-c, --columns <columns>: Columns to display. Either a comma-separated list of column names, or multiple invocations of the flag. Available columns: key, group, deps, kinds, description, tags, cron, is_executable

--verbose: Enable verbose output for debugging.

--target-path <target_path>: Specify a directory to use to load the context for this command. This will typically be a folder with a dg.toml or pyproject.toml file in it.

envs

List environment variables from the .env file of the current project.

dg list envs [OPTIONS]

Options:

--target-path <target_path>: Specify a directory to use to load the context for this command. This will typically be a folder with a dg.toml or pyproject.toml file in it.

--verbose: Enable verbose output for debugging.

projects

List projects in the current workspace.

dg list projects [OPTIONS]

Options:

--verbose: Enable verbose output for debugging.

--target-path <target_path>: Specify a directory to use to load the context for this command. This will typically be a folder with a dg.toml or pyproject.toml file in it.

registry-modules

List dg plugins and their corresponding objects in the current Python environment.

dg list registry-modules [OPTIONS]

Options:

--json: Output as JSON instead of a table.

--target-path <target_path>: Specify a directory to use to load the context for this command. This will typically be a folder with a dg.toml or pyproject.toml file in it.

--verbose: Enable verbose output for debugging.

dg plus

Commands for interacting with Dagster Plus.

dg plus [OPTIONS] COMMAND [ARGS]...

create

Commands for creating configuration in Dagster Plus.

dg plus create [OPTIONS] COMMAND [ARGS]...

ci-api-token

Create a Dagster Plus API token for CI.

dg plus create ci-api-token [OPTIONS]

Options:

--description <description>: Description for the token

--verbose: Enable verbose output for debugging.

env

Create or update an environment variable in Dagster Plus.

dg plus create env [OPTIONS] ENV_NAME [ENV_VALUE]

Options:

--from-local-env: Pull the environment variable value from your shell environment or project .env file.

--scope <scope>

The deployment scope to set the environment variable in. Defaults to all scopes.

Options: full | branch | local

--global: Whether to set the environment variable at the deployment level, for all locations.

-y, --yes: Do not confirm the creation of the environment variable, if it already exists.

--target-path <target_path>: Specify a directory to use to load the context for this command. This will typically be a folder with a dg.toml or pyproject.toml file in it.

--verbose: Enable verbose output for debugging.

Arguments:

ENV_NAME: Required argument

ENV_VALUE: Optional argument

deploy

Deploy a project or workspace to Dagster Plus. Handles all state management for the deploy session, building and pushing a new code artifact for each project.

To run a full end-to-end deploy, run dg plus deploy. This will start a new session, build and push the image for the project or workspace, and inform Dagster+ to deploy the newly built code.

Each of the individual stages of the deploy is also available as its own subcommand for additional customization.

dg plus deploy [OPTIONS] COMMAND [ARGS]...

Options:

--deployment <deployment>

Name of the Dagster+ deployment to which to deploy (or use as the base deployment if deploying to a branch deployment). If not set, defaults to the value set by dg plus login.

Default: 'deployment'

--organization <organization>

Dagster+ organization to which to deploy. If not set, defaults to the value set by dg plus login.

Default: 'organization'

--python-version <python_version>

Python version used to deploy the project. If not set, defaults to the calling process’s Python minor version.

Options: 3.9 | 3.10 | 3.11 | 3.12

--deployment-type <deployment_type_str>

Whether to deploy to a full deployment or a branch deployment. If unset, will attempt to infer from the current git branch.

Options: full | branch

--agent-type <agent_type_str>

Whether this a Hybrid or serverless code location.

Options: serverless | hybrid

-y, --yes: Skip confirmation prompts.

--git-url <git_url>

--commit-hash <commit_hash>

--location-name <location_names>: Name of the code location to set the build output for. Defaults to the current project’s code location, or every project’s code location when run in a workspace.

--status-url <status_url>

--snapshot-base-condition <snapshot_base_condition_str>: Options: on-create | on-update

--use-editable-dagster: Install all Dagster package dependencies from a local Dagster clone. The location of the local Dagster clone will be read from the DAGSTER_GIT_REPO_DIR environment variable.

--target-path <target_path>: Specify a directory to use to load the context for this command. This will typically be a folder with a dg.toml or pyproject.toml file in it.

--verbose: Enable verbose output for debugging.

Environment variables:

DAGSTER_CLOUD_DEPLOYMENT: Provide a default for --deployment

DAGSTER_CLOUD_ORGANIZATION: Provide a default for --organization

build-and-push

Builds a Docker image to be deployed, and pushes it to the registry that was configured when the deploy session was started.

dg plus deploy build-and-push [OPTIONS]

Options:

--agent-type <agent_type_str>

Whether this a Hybrid or serverless code location.

Options: serverless | hybrid

--python-version <python_version>

Python version used to deploy the project. If not set, defaults to the calling process’s Python minor version.

Options: 3.9 | 3.10 | 3.11 | 3.12

--location-name <location_names>: Name of the code location to set the build output for. Defaults to the current project’s code location, or every project’s code location when run in a workspace.

--use-editable-dagster: Install all Dagster package dependencies from a local Dagster clone. The location of the local Dagster clone will be read from the DAGSTER_GIT_REPO_DIR environment variable.

--target-path <target_path>: Specify a directory to use to load the context for this command. This will typically be a folder with a dg.toml or pyproject.toml file in it.

--verbose: Enable verbose output for debugging.

finish

Once all needed images have been built and pushed, completes the deploy session, signaling to the Dagster+ API that the deployment can be updated to the newly built and pushed code.

dg plus deploy finish [OPTIONS]

Options:

--location-name <location_names>: Name of the code location to set the build output for. Defaults to the current project’s code location, or every project’s code location when run in a workspace.

--verbose: Enable verbose output for debugging.

--target-path <target_path>: Specify a directory to use to load the context for this command. This will typically be a folder with a dg.toml or pyproject.toml file in it.

refresh-defs-state

[Experimental] If using StateBackedComponents, this command will execute the refresh_state on each of them, and set the defs_state_info for each location.

dg plus deploy refresh-defs-state [OPTIONS]

Options:

--use-editable-dagster: Install all Dagster package dependencies from a local Dagster clone. The location of the local Dagster clone will be read from the DAGSTER_GIT_REPO_DIR environment variable.

--target-path <target_path>: Specify a directory to use to load the context for this command. This will typically be a folder with a dg.toml or pyproject.toml file in it.

--verbose: Enable verbose output for debugging.

--management-type <management_type>

Only refresh components with the specified management type. Can be specified multiple times to include multiple types. By default, refreshes VERSIONED_STATE_STORAGE and LOCAL_FILESYSTEM components.

Options: LOCAL_FILESYSTEM | VERSIONED_STATE_STORAGE

set-build-output

If building a Docker image was built outside of the dg CLI, configures the deploy session to indicate the correct tag to use when the session is finished.

dg plus deploy set-build-output [OPTIONS]

Options:

--image-tag <image_tag>: Required Tag for the built docker image.

--location-name <location_names>: Name of the code location to set the build output for. Defaults to the current project’s code location, or every project’s code location when run in a workspace.

--verbose: Enable verbose output for debugging.

--target-path <target_path>: Specify a directory to use to load the context for this command. This will typically be a folder with a dg.toml or pyproject.toml file in it.

start

Start a new deploy session. Determines which code locations will be deployed and what deployment is being targeted (creating a new branch deployment if needed), and initializes a folder on the filesystem where state about the deploy session will be stored.

dg plus deploy start [OPTIONS]

Options:

--deployment <deployment>

Name of the Dagster+ deployment to which to deploy (or use as the base deployment if deploying to a branch deployment). If not set, defaults to the value set by dg plus login.

Default: 'deployment'

--organization <organization>

Dagster+ organization to which to deploy. If not set, defaults to the value set by dg plus login.

Default: 'organization'

--deployment-type <deployment_type_str>

Whether to deploy to a full deployment or a branch deployment. If unset, will attempt to infer from the current git branch.

Options: full | branch

-y, --yes: Skip confirmation prompts.

--git-url <git_url>

--commit-hash <commit_hash>

--location-name <location_names>: Name of the code location to set the build output for. Defaults to the current project’s code location, or every project’s code location when run in a workspace.

--target-path <target_path>: Specify a directory to use to load the context for this command. This will typically be a folder with a dg.toml or pyproject.toml file in it.

--status-url <status_url>

--snapshot-base-condition <snapshot_base_condition_str>: Options: on-create | on-update

--verbose: Enable verbose output for debugging.

Environment variables:

DAGSTER_CLOUD_DEPLOYMENT: Provide a default for --deployment

DAGSTER_CLOUD_ORGANIZATION: Provide a default for --organization

pull

Commands for pulling configuration from Dagster Plus.

dg plus pull [OPTIONS] COMMAND [ARGS]...

env

Pull environment variables from Dagster Plus and save to a .env file for local use.

dg plus pull env [OPTIONS]

Options:

--verbose: Enable verbose output for debugging.

--target-path <target_path>: Specify a directory to use to load the context for this command. This will typically be a folder with a dg.toml or pyproject.toml file in it.

dg scaffold

Commands for scaffolding Dagster entities.

dg scaffold [OPTIONS] COMMAND [ARGS]...

Commands:

build-artifacts: Scaffolds a Dockerfile to build the given Dagster project or workspace.

component

Scaffold of a custom Dagster component type.

This command must be run inside a Dagster project directory. The component type scaffold

will be placed in submodule <project_name>.lib.<name>.

defs: Commands for scaffolding Dagster code.

github-actions

Scaffold a GitHub Actions workflow for a Dagster project.

This command will create a GitHub Actions workflow in the .github/workflows directory.

Examples

dg scaffold defs

Note: Before scaffolding definitions with dg, you must create a project with the create-dagster CLI and activate its virtual environment.

You can use the dg scaffold defs command to scaffold a new asset underneath the defs folder. In this example, we scaffold an asset named my_asset.py and write it to the defs/assets directory:

dg scaffold defs dagster.asset assets/my_asset.py

Creating a component at /.../my-project/src/my_project/defs/assets/my_asset.py.

Once the asset has been scaffolded, we can see that a new file has been added to defs/assets, and view its contents:

tree

.
├── pyproject.toml
├── src
│ └── my_project
│     ├── __init__.py
│     └── defs
│         ├── __init__.py
│         └── assets
│             └── my_asset.py
├── tests
│ └── __init__.py
└── uv.lock

cat src/my_project/defs/assets/my_asset.py

import dagster as dg

@dg.asset
def my_asset(context: dg.AssetExecutionContext) -> dg.MaterializeResult: ...

Note: You can run dg scaffold defs from within any directory in your project and the resulting files will always be created in the <project-name>/src/<project_name>/defs/ folder.

In the above example, the scaffolded asset contains a basic commented-out definition. You can replace this definition with working code:

import dagster as dg


@dg.asset(group_name="my_group")
def my_asset(context: dg.AssetExecutionContext) -> None:
    """Asset that greets you."""
    context.log.info("hi!")

To confirm that the new asset now appears in the list of definitions, run dg list defs:

dg list defs

┏━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Section ┃ Definitions                                                     ┃
┡━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Assets  │ ┏━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━┳━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┓ │
│         │ ┃ Key      ┃ Group    ┃ Deps ┃ Kinds ┃ Description            ┃ │
│         │ ┡━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━╇━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━┩ │
│         │ │ my_asset │ my_group │      │       │ Asset that greets you. │ │
│         │ └──────────┴──────────┴──────┴───────┴────────────────────────┘ │
└─────────┴─────────────────────────────────────────────────────────────────┘

dg scaffold build-artifacts

Note: Before scaffolding build artifacts with dg, you must create a Dagster project with the create-dagster CLI and activate its virtual environment.

If you have a Dagster+ Hybrid deployment, you can use dg scaffold build-artifacts to scaffold a deployment configuration file (build.yaml) and a Dockerfile for your Dagster project:

dg scaffold build-artifacts
Scaffolding build artifacts for my-project...
Project build config created at /.../my-project/build.yaml.
Dockerfile created at /.../my-project/Dockerfile.

dg scaffold github-actions

Note: Before scaffolding GitHub Actions with dg, you must create a Dagster project with the create-dagster CLI and activate its virtual environment. You will also need to place the project under version control, which you can do by running git init in the project root directory.

You can use the dg scaffold github-actions command to scaffold a GitHub CI/CD workflow YAML file in a .github/workflows directory:

dg scaffold github-actions
Dagster Plus organization name: ExampleCo
Default deployment name [prod]:
Deployment agent type:  (serverless, hybrid): serverless
Using serverless workflow template.

GitHub Actions workflow created successfully. Commit and push your changes in order to deploy to Dagster Plus.

You will need to set up the following secrets in your GitHub repository using
the GitHub UI or CLI (https://cli.github.com/):
dg plus create ci-api-token --description 'Used in my-project GitHub Actions' | gh secret set DAGSTER_CLOUD_API_TOKEN

dg check​

defs​

toml​

yaml​

dg dev​

dg launch​

dg list​

component-tree​

components​

defs​

envs​

projects​

registry-modules​

dg plus​

create​

ci-api-token​

env​

deploy​

build-and-push​

finish​

refresh-defs-state​

set-build-output​

start​

login​

pull​

env​

dg scaffold​

Examples​

dg scaffold defs​

dg scaffold build-artifacts​

dg scaffold github-actions​

dg check

defs

toml

yaml

dg dev

dg launch

dg list

component-tree

components

defs

envs

projects

registry-modules

dg plus

create

ci-api-token

env

deploy

build-and-push

finish

refresh-defs-state

set-build-output

start

login

pull

env

dg scaffold

Examples

dg scaffold defs

dg scaffold build-artifacts

dg scaffold github-actions