Skip to main content
Version: 0.29

Upgrade to Astro CLI version 1.0+

Astro CLI version 1.0+ delivers several new features to Astronomer Software and establishes a shared CLI framework across all Astronomer products.

Several commands and their flags have been updated as part of this release, resulting in breaking changes for users of Astronomer Software. Use this document to learn about these breaking changes and prepare for your upgrade to Astro CLI version 1.0+.

This information applies only to users who are upgrading the Astro CLI from a pre-1.0 to a post-1.0 version. To install the latest version of the CLI for the first time, see Install the CLI.

Upgrade checklist

Before installing Astro CLI version 1.0+, complete all of the following steps:

  • Make sure you are running Astronomer Software version 0.28+. If you're not sure, ask your system administrator.
  • Review the Breaking changes section in this document.
  • Update any CI/CD pipelines or automated processes that use Astro CLI commands to ensure that these commands do not break after you upgrade.
  • Review any custom shortcuts in your local CLI terminal to ensure that your shortcuts do not run any CLI commands that are no longer supported.

After you complete these steps, upgrade to Astro CLI version 1.0+ by following the instructions in Install the CLI.

Features

New astro dev restart command to test local changes

For users making continuous changes to an Astro project locally, the Astro CLI now supports a new astro dev restart command. With this new command, you no longer need to run astro dev stop followed by astro dev start when you're testing locally.

For more information, see CLI command reference.

New command to run DAG unit tests with pytest

You can now run custom unit tests for all DAGs in your Astro project with astro dev pytest, a new Astro CLI command that uses pytest, a common testing framework for Python. As part of this change, new Astro projects created with astro dev init now include a tests directory, which includes one example unit test built by Astronomer.

In addition to running tests locally, you can also run astro dev pytest as part of the deploy process to Astronomer Software. For more information, see CLI command reference.

New command to parse DAGs for errors

The new astro dev parse command allows you to run a basic test against your Astro project to ensure that your DAGs are able to to render in the Airflow UI. This includes the DAG integrity test that is run with astro dev pytest, which checks that your DAGs are able to to render in the Airflow UI. Now, you can quickly run astro dev parse and see import and syntax errors directly in your terminal without having to restart all Airflow services locally.

For more complex testing, Astronomer recommends using astro dev pytest to run custom tests in your project. For more information on astro dev parse, see the CLI command reference.

Breaking changes

This topic contains all information related to breaking changes included in Astro CLI version 1.0+ relative to version 0.28 and below.

This topic does not include information about new features and changes that are not breaking. For a summary of all changes, see the CLI release notes.

Podman is not supported in version 1.0+

Running the Astro CLI with Podman containers is currently unsupported in version 1.0+. Podman functionality is still actively maintained in patches for versions 0.29 and 0.28. To continue using Podman to run the Astro CLI, do not upgrade to version 1.0+ until further support is announced.

astro dev init: New --use-astronomer-certified Flag Required for All New Projects Deployed to Software

When you create a new Astro project with the astro dev init command, you must now specify the --use-astronomer-certified flag if you want to deploy the project to a Deployment on Astronomer Software. This flag initializes your project with the latest Astronomer Certified version.

If you don't specify this flag, the project is initialized with an Astro Runtime image. Support for Astro Runtime on Astronomer Software is coming soon.

# Before upgrade
astro dev init

# After upgrade
astro dev init --use-astronomer-certified

astro auth login is now astro login

The previous astro auth login and astro auth logout commands have been simplified:

# Before upgrade
astro auth login <domain>
astro auth logout

# After upgrade
astro login <domain>
astro logout

astro workspace create/update now takes all configurations as flags

When you specify configurations for a Workspace using astro workspace create or astro workspace update, you must now specify those properties with new flags.

# Before upgrade
astro workspace create label=my-workspace

# After upgrade
astro workspace create --label=my-workspace

astro workspace create/update: --desc flag has been renamed to --description

The flag for specifying a description for a Workspace has been renamed from --desc to --description.

# Before upgrade
astro workspace create label=my-workspace --desc="my description"

# After upgrade
astro workspace create --label=my-workspace --description="my description"

astro workspace user add: User email is now specified as a flag

You must now specify a new user's email using the --email flag when running astro workspace

# Before upgrade
astro workspace user add email-to-add@astronomer.io --role WORKSPACE_VIEWER
# After upgrade
astro workspace user add --email email-to-add@astronomer.io --role WORKSPACE_VIEWER

astro deploy Now accepts a Deployment ID instead of a release name

To deploy code to a specific Deployment without manually selecting a Deployment from a list, you must now specify that Deployment's ID instead of its release name when running astro deploy.

# Before upgrade
astro deploy <release-name>

# After upgrade
astro deploy <deployment-id>

astro workspace sa get is now astro workspace sa list

# Before upgrade
astro workspace sa get
# After upgrade
astro workspace sa list

astro deployment/workspace sa create: --role only accepts full role names

The --role flag now accepts either WORKSPACE_EDITOR, WORKSPACE_ADMIN, or WORKSPACE_VIEWER.

# Before upgrade
astro workspace sa create --role viewer

# After upgrade
astro workspace sa create --role WORKSPACE_VIEWER

astro deployment create/update now takes all properties as flags

You must now specify a Deployment's properties using flags when you run astro deployment create or astro deployment update.

# Before upgrade
astro deployment create my-deployment --executor=local

# After upgrade
astro deployment create --label=my-deployment --executor=local

astro deployment user list Now Takes Deployment ID as a Flag

To list users that have access to a specific Deployment, you must now use the --deployment-id flag when running astro deployment user list.

# Before upgrade
astro deployment user list <deployment-id>

# After upgrade
astro deployment user list --deployment-id=<deployment-id>

astro deployment user add: --email flag is now required

You must now specify a user's email using the --email flag when running astro deployment user add.

# Before upgrade
astro deployment user add <email> --deployment-id=<deployment-id>

# After upgrade
astro deployment user add --email=<email> --deployment-id=<deployment-id>

astro deployment user delete is now astro deployment user remove

# Before upgrade
astro deployment user delete <email> --deployment-id=<deployment-id>

# After upgrade
astro deployment user remove <email> --deployment-id=<deployment-id>

astro logs <component> is now deprecated

The astro logs command has been removed. This command has been unavailable for the last several CLI releases. Use astro dev logs to view logs locally or astro deployment logs <component> to view logs for a Deployment hosted on Astronomer Software.

astro cluster list/switch is now astro context list/switch

# Before upgrade
astro cluster list

# After upgrade
astro context list

astro deployment sa create: --system-sa and --user-id are deprecated

The --system-sa and --user-id flags have been deprecated for astro deployment sa create. These flags have not been functional for the last several CLI versions.

astro dev init: shortcut for --airflow-version is now -a

The shortcut for specifying an Astronomer Certified version for astro dev init has been changed from -v to -a.

# Before upgrade
astro dev init -v=2.3.0

# After upgrade
astro dev init -a=2.3.0