This document provides a summary of all changes made to the Astro CLI. For general product release notes, go to Astro Release Notes. If you have any questions or a bug to report, contact Astronomer support.
Release date: May 20, 2026
astro deploy with --image-name against Deployments that have Dag-only deploys disabled, including Remote Execution Deployments. A regression in 1.42.0 caused these deploys to fail with a DAG-only deploys are not enabled for this Deployment error.astro dev start with the Podman container engine on Windows. Native Podman commands no longer receive an unsupported npipe:// connection value, so local project setup completes successfully.Release date: April 30, 2026
Astro CLI 1.42.0 fails to deploy with astro deploy --image-name against Deployments that have Dag-only deploys disabled, including Remote Execution Deployments. The deploy returns a DAG-only deploys are not enabled for this Deployment error.
Impact: You cannot push a custom image to a Remote Execution Deployment, or to any Deployment without Dag-only deploys enabled, using --image-name on Astro CLI 1.42.0.
Solution: Upgrade to Astro CLI 1.42.1 or later. This issue is fixed in Astro CLI version 1.42.1.
astro otto commandA new astro otto command launches Otto, Astronomer’s data engineering agent, in your terminal. The CLI handles Otto binary downloads, version management, and authentication automatically.
Standalone mode now supports Airflow 2 (Astro Runtime 13.x) projects in addition to Airflow 3. Run astro dev start --standalone from any Astro project to start a local Airflow environment without Docker, regardless of the Airflow major version.
--json and --output flags for list commandsMost list commands now accept --json, --output (-o), and --template flags to produce machine-readable output for scripts and CI/CD pipelines. The default table output is unchanged.
The following commands support the new flags:
astro dev psastro deployment listastro deployment user listastro deployment team listastro workspace listastro workspace user listastro workspace team listastro organization listastro organization user listastro organization team listFor example:
--json and --output are mutually exclusive.
astro dev start and astro dev object import now apply variables, connections, and pools from airflow_settings.yaml through the Airflow REST API instead of running a separate Airflow CLI command per item. A typical settings file with several connections, variables, and pools that previously took more than a minute now completes in a few seconds.
The CLI now supports Astro Private Cloud 2.0. Deployment, image update, and Dag-only deploy operations against Astro Private Cloud 2.0. Compatibility with earlier Astro Private Cloud versions is preserved.
astro dev init and astro dev start --standalone now skip Astro Runtime versions marked as yanked when picking a default image tag, so new projects no longer pin to a yanked Runtime version. This does not affect projects that already pin a floating tag in their Dockerfile, because Docker resolves floating tags through the registry.--spec-url flag on astro api cloud now accepts local file paths in addition to HTTP URLs. Supported forms include absolute paths, relative paths, paths starting with ~/, and file:// URIs. Local specs are read fresh on every command invocation, and the --spec-token-env-var flag is ignored for local files.astro deployment logs with --log-count now paginates results so the command returns the full requested number of log lines. Previously, results were capped at the API’s per-page limit regardless of the requested count.docker or standalone) in anonymous telemetry. To opt out of telemetry, run astro telemetry disable or set the ASTRO_TELEMETRY_DISABLED environment variable to 1.astro dev start --standalone to use your project’s plugins/ folder for plugins_folder. Previously, plugins_folder defaulted to .astro/standalone/plugins/, so plugins from your project were not loaded.astro deploy with --image-name to skip Dockerfile parsing. Projects that build their image in a separate pipeline and reference it through --image-name no longer fail when no Dockerfile is present in the project directory.Release date: April 20, 2026
astro auth commandA new astro auth command group provides commands for authenticating to Astro or Astro Private Cloud:
astro auth login: Authenticate to Astro or Astro Private Cloud. The existing astro login command is now an alias for this command.astro auth logout: Log out of the Astro CLI. The existing astro logout command is now an alias for this command.astro auth token: Print the current authentication token to standard output. This is useful for using the token in scripts or CI/CD pipelines. Use the --domain flag to print the token for a specific context domain.astro api registry commandA new astro api registry command lets you make HTTP requests to the Airflow Provider Registry API directly from the Astro CLI. No authentication is required. The command supports endpoint discovery with ls and describe, jq filters, Go template output, and a --generate flag to produce equivalent curl commands.
-f (--force) flag to astro dev init to initialize a project without confirmation, even in a non-empty directory.-f (--force) flag to astro deployment create to create a Deployment without prompting for confirmation.-f (--force) flag to astro organization team update, astro organization team delete, and the astro organization team user add and remove subcommands to skip confirmation prompts for Identity Provider (IdP)-managed teams.-f (--force) flag on astro deploy now also skips the “No Dags found” warning in addition to parse errors and uncommitted changes.astro api cloud.astro dev run to propagate non-zero exit codes from the executed command.astro dev restart with --allow-existing to preserve the virtual environment in standalone mode.astro dev start in standalone mode to add include/ to PYTHONPATH.astro-agent in Airflow version resolution.Release date: March 12, 2026
astro dev pytest command to use docker cp instead of bind-mounts for copying test files into the container.Release date: March 10, 2026
astro dev build commandA new astro dev build command builds your Astro project into a Docker image without starting a local Airflow environment. Use this command to verify that your project builds successfully before deployment. The command supports --no-cache and --image-name flags.
astro api commandA new astro api command lets you make authenticated API requests to Astronomer services directly from the Astro CLI:
astro api airflow: Make requests to the Airflow REST API for a local or deployed Airflow instance. The CLI automatically detects the Airflow version and resolves the OpenAPI spec. Supports endpoint discovery via ls and describe, pagination, jq filters, Go template output, and a --curl flag to generate equivalent curl commands.astro api cloud: Make requests to the Astro platform API using your current context’s bearer token. Supports the same output formatting and discovery features as astro api airflow.You can now run a local Airflow environment without Docker using standalone mode. Standalone mode runs Airflow directly on your machine using a virtual environment. This initial release supports Airflow 3 projects only.
To use standalone mode, set it as the default for a project:
Or use the --standalone flag to override for a single command:
All existing astro dev commands work in standalone mode, including run, bash, parse, pytest, object import, and object export. The build, upgrade-test, and compose-export commands are not available in standalone mode.
When you run astro dev start, a built-in reverse proxy now routes <project>.localhost:6563 to the correct local Airflow instance. This lets you run multiple Airflow projects simultaneously without manually configuring ports. The first project keeps the default port (8080), and subsequent projects are assigned random ports automatically.
To view all running projects and their routes, run astro dev proxy status. To disable the proxy for a single start, use astro dev start --no-proxy.
When working in a git worktree, the URL includes both the worktree and repository names: <worktree>.<repo>.localhost:6563.
astro telemetry commandA new astro telemetry command lets you manage anonymous usage telemetry for the Astro CLI. Telemetry is enabled by default and sends anonymous usage data using a fire-and-forget pattern with no impact on CLI responsiveness. Use astro telemetry disable or set the ASTRO_TELEMETRY_DISABLED environment variable to 1 to opt out.
astro registry commandThe astro registry command and its subcommands (dag add, provider add) have been removed.
--kill (-k) flag to astro dev restart. When used, this flag kills all running containers and removes all data before restarting. This is equivalent to running astro dev kill followed by astro dev start.--fix flag to astro dev upgrade-test to automatically fix linting issues identified by the upgrade test using ruff.--no-dags-base-dir flag to astro deploy for use with --dags. By default, Dag-only deploys place files in a dags/ folder prefix. With --no-dags-base-dir, files are placed at the bundle root for compatibility with Airflow 3, which adds the bundle root to sys.path instead of the dags/ folder.--api-server and --dag-processor component filter flags to astro dev logs.Release date: February 17, 2026
--session-id flag with astro ide project import to specify a session ID when importing an Astro IDE project.astro remote deploy now blocks deployment of client images with an Astro Runtime version newer than the target Deployment’s Astro Runtime version to ensure compatibility.Release date: November 4, 2025
astro remote deploy to correctly install dependencies from requirements-client.txt and packages-client.txt during image build.Release date: October 27, 2025
Astro CLI 1.38.0 installs Remote Execution Agent Python and system dependencies from requirements.txt and packages.txt instead of requirements-client.txt and packages-client.txt when you run astro remote deploy. As a result, dependencies meant for the client may not be installed on the Remote Execution Agent as expected.
Impact: If your remote execution depends on packages listed only in requirements-client.txt or packages-client.txt, these will not be installed, which can lead to missing dependencies or failures at runtime.
Solution: Upgrade to Astro CLI 1.38.1 or later. This issue is fixed in Astro CLI version 1.38.1.
astro dev initYou can now create a remote execution project using astro dev init. Setting remote execution mode prompts you to add the resources necessary for configuring your remote execution configuration.
astro remote deploy command by default--force-upgrade-to-af3 flag from astro deploy--wait-time flag for astro deployment create, astro deploy, astro dbt deploy commands, to allow you to configure wait time for the operation to finish. The default wait time is now 5 minutes.Release date: October 14, 2025
Added support for Astro Private Cloud 1.0, including the ability to push images and dags to separate data plane clusters.
get, list, and update commands now display a new REMOTE EXECUTION column that indicates if Remote Execution is enabled for a Deployment.--workspace-id flag has been added to organization switch for selecting a Workspace programmatically.default_pool correctly by sending only slots and include_deferred with an update_mask.Release date: September 10, 2025
This feature is in Public Preview.
Added the following commands so that you can work with the Astro IDE from the Astro CLI:
astro ide project export: Export your current local project to Astro IDE.astro ide project import: Import an existing Astro IDE project into your local environment for development or editing.astro ide project list: List all Astro IDE projects you have access to.Enhanced error handling during Docker image pushes in astro deploy. When a 403 Forbidden error occurs, the CLI now displays actionable troubleshooting guidance, including steps for clearing Docker credentials, disabling the containerd snapshotter, and a link to detailed support documentation.
airflow_settings.yaml, is present.Release date: July 31, 2025
Astro CLI 1.35.1 introduces full compatibility with Apache Airflow 3, including support for the Astro Executor and Remote Execution Deployments on Astro. This release also adds the ability to manage connections, variables, and pools for Airflow 3 environments.
astro deployment create and astro deployment updateYou can now use the new AstroExecutor option as an executor type for Airflow 3 Deployments. When using AstroExecutor, you can enable Remote Execution by setting the --remote-execution-enabled flag when you use astro deployment create. If Remote Execution is enabled, you can also configure additional Remote Execution mode Deployment settings with the following flags:
--allowed-ip-address-ranges: Limit the Deployment’s incoming traffic to the Remote Agents in your environment.--task-log-bucket: Specify the cloud storage bucket for task log storage.--task-log-url-pattern: Specify the URL template to link to task logs stored in an external logging provider from the Airflow UI.--webserver as --apiserver for Airflow 3 environments to reflect the updated component architecture.Release date: July 1, 2025
The Astro CLI 1.35.0 was restricted from use on July 1, 2025, after its initial release. After upgrading to this version, v1.35.0 caused automatic, unintended updates to worker queues. Astro automatically blocks any requests coming from this CLI version.
See the Astro CLI Release and lifecycle policy for more information about different release channels and a list of restricted CLI versions.
Release date: May 27, 2025
astro dev init command to no longer require a container runtime during project initialization. This means you do not need to have something like Docker or Podman installed locally on your machine to run astro dev init succesfully.astro dev upgrade-test to lint the entire project, not just the dags/ directory, so issues in other directories like include/ are now also detected.Release date: April 22, 2025
Astro CLI 1.34.0 adds support for Apache Airflow 3, including local development with Airflow 3 and the ability to test your project locally for upgrade incompatibilities.
See Upgrade to Airflow 3 for steps to upgrade your Astro project from Airflow 2 to Airflow 3.
Release date: March 17, 2025
Release date: February 20, 2025
astro dev parse and astro dev pytest commands are now displayed at the warn log level by default, making them visible without the --verbosity=debug flag for easier troubleshooting.Release date: January 16, 2025
astro deploy on Astronomer SoftwareYou can now use the --image flag with astro deploy to trigger an image-only deploy on Astronomer Software.
You can also specify an image with the --image-name for a astro deploy on Astronomer Software. If you specify an image, you must also specify the image’s Runtime version with the --runtime-version flag. You can also use the new --remote flag with --image-name to directly point the deployment to the remote image and skip pushing the image.
You can now use the Orbstack Container Runtime Engine with the Astro CLI on macOS. If Orbstack is running, containers start seamlessly. If not, the Orbstack app launches automatically, and containers start in the background. You can close the app while it continues running. This feature is available for macOS only. Windows and Linux users will need to start their runtime manually.
sha_as_tag for Astronomer Software to use the SHA Digest value when making a call to the updateDeploymentImage endpoint in Houston, instead of the Runtime version tag.deployments list --all would not work on Astronomer Software.Release date: January 8, 2025
Release date: December 17, 2024
You can now create local Astro projects without manually installing a container management engine, on all supported operating systems. When you install the Astro CLI with Homebrew or Winget, it includes a pre-configured Podman container runtime. If you don’t want to install Podman with the Astro CLI, you can opt out during installation, allowing the Astro CLI to use your existing runtime setup. See Install the Astro CLI.
astro dev init, simplifying project initialization by automatically creating and initializing a new directory.container.binary parameter for the Astro CLI was set to docker by default. Now, the Astro CLI will attempt to auto-detect the container runtime to use, checking for docker then podman in that order. You can override the auto-detection with astro config set container.binary.Release date: November 22, 2024
--from-template flag to setup template based projectYou can now specify a template name such as etl, dbt-on-astro, generative-ai, or learning-airflow with the --from-template flag for astro dev init and the CLI sets up an Astro project based on the provided template.
--show-workload-identity flag to fetch workload identity of DeploymentYou can now fetch the workload identity value of a Deployment with the --show-workload-identity flag for astro deployment inspect.
astro dev start for Podman users.Release date: October 16, 2024
You can now add custom deploy descriptions during the astro deploy CLI command on Astronomer Software to enhance traceability and clarity in the deploy process. If you don’t provide a description, the system will automatically assign a default description based on the code deploy type. For example, the default description for a dag-only deploy would be Deployed via <astro deploy --dags>.
astro deployment create to create in Azure by default for AstroRelease date: September 9, 2024
extra_large option for the --scheduler flag. This requires a minimum Astro Runtime version of 9.7.0.--workload-identity flag or by adding it to the Deployment config file with the workload_identity field.See astro deployment create and astro deployment update for more information.
Release date: July 25, 2024
Release date: July 24, 2024
This feature is in Labs. Contact your account team to enable this feature.
You can now deploy a dbt project to Astro using the Astro CLI. See the following reference pages for more information:
workspace-id. See astro workspace switch.astro deployment inspect --key configuration.is_development_mode was printing wrong the value.Release date: May 16, 2024
Release date: May 16, 2024
You can now filter logs for specific Deployment components using the following new flags for astro deployment logs:
--webserver--scheduler--triggerer--workerYou can now exclude dag files from being tested when you run astro dev parse.
All new Astro projects that you create with astro dev init now include a file named .astro/dag_integrity_exceptions.txt. Add the names of dags to this file to exclude them from being tested when you run astro dev parse. This allows you to exclude dags that you know will not pass your tests.
To use this feature in an existing Astro project, delete the .astro/test_dag_integrity_default.py file in your Astro project, then run astro dev init. After you run this command, the Astro CLI creates a new default test file along with a .astro/dag_integrity_exceptions.txt text file.
astro deploy --image.2>/dev/null | head to commands to disregard upgrade messages. For example, running astro completion bash 2>/dev/null | head ensures that the resulting bash script remains unaffected by the upgrade message.--development-mode disable flag with astro deployment update to turn off development mode for an existing Deployment. Note that you still cannot turn on development mode for an existing Deployment.upgrade-test command now returns the correct error code, ensuring accurate feedback during testing and CI/CD.Release date: April 24, 2024
You can now use the Astro CLI to manage Organization and Workspace API tokens at the Workspace and Deployment level using the following commands:
astro deployment token organization-tokenastro deployment token workspace-tokenastro workspace token organization-tokenFor more information about this feature, see:
astro deployment inspect generated an incorrect Airflow API URL.astro deployment upgrade-checks to fail against valid inputs.Release date: March 28, 2024
You can now manage Deployment API tokens using the following CLI commands:
astro deployment token createastro deployment token listastro deployment token updateastro deployment token rotateastro deployment token deleteastro dev init.deployment variable create where it would cut off the new variables value at the first ”=” character.astro dev start —deployment-id was not creating local connections correctly in some scenarios.astro deployment commands could only list 20 deployments. Now the commands will list up to 1000 for each workspace.Release date: February 29, 2024
Release date: February 27, 2024
You can now use the Astro CLI to hibernate or wake up a development Deployment. These commands work well in automated processes where a Deployment requires flexibility for when it hibernates. Note that you can hibernate a Deployment only if you enable Development Mode when you create the Deployment.
Use the following new commands to hibernate development Deployments regardless of their existing hibernation schedule:
Additionally, you can create new development Deployments and configure long-term hibernation schedules for them using astro deployment create.
astro deployment variable list --save didn’t format secret environment variables correctly.Release date: February 14, 2024
The following flags have been updated, but will continue to work with a deprecation notice until the v1.25.0 release of the Astro CLI:
astro deployment logs --key-word ia a new flag that allows you to search your Deployment’s logs for an exact key word or phrase.astro deployment create --cluster-type is now astro deployment create --type.astro deployment create --enforce-cicd is now astro deployment create --cicd-enforcement.You can now use Deployment files or the Astro CLI to create or update Kubernetes worker configurations.
Deployment files now include some new and updated fields for Deployment configuration to match the options available in the Astro UI. This also allows you to create or update Kubernetes worker configurations directly, instead of requiring you to update the worker resources by changing the Kubernetes worker queue configuration.
You can now use the default_task_pod_cpu, default_task_pod_memory, default_worker_type, resource_quota_cpu, and resource_quota_memory fields in a Deployment file to update your Kubernetes workers instead of creating or updating a Kubernetes default worker queue.
With this new functionality, the following commands to update a Deployment running the Kubernetes executor continue to work, but display a deprecation notice:
astro deployment worker-queue createastro deployment worker-queue updateInstead, you can use the new --default-task-pod-cpu, --default-task-pod-memory, --resource-quota-cpu, or --resource-quota-memory flags with astro deployment create and astro deployment update to edit your Kubernetes worker configuration using the Astro CLI.
The following changes have been made to the format of Deployment files:
cluster_name for standard Deployment files.scheduler_size is no longer case sensitive.cloud_provider are now gcp, aws, and azure. This input is not case sensitive.deployment_type now include standard, dedicated, and hybrid in addition to the existing values of hosted_shared, hosted_dedicated, and hosted_standard. This input is not case sensitiveexecutor field are now include celery and kubernetes. CeleryExecutor and KubernetesExecutor still work. This input is not case sensitive, so, for example, celeryexecutor still works.default_task_pod_cpu, default_task_pod_memory, resource_quota_cpu, and resource_quota_memory are new fields for Astro Hosted deployments.default_worker_type is a new field for Hybrid deployments that use the Kubernetes executor.astro deploy --dags. See Deploy dags on Astronomer Software.astro deployment logs --key-word is a new flag that allows you to search your audit logs for an exact key word or phrase.ASTRO_API_TOKEN, ASTRONOMER_KEY_ID, or ASTRONOMER_KEY_SECRET environment variables, auto-select is enabled. This is important because it ensures that if you have CI/CD scripts that rely on auto-select, they will continue to work.auto_select. If auto-select is set to true in the config file, auto-select is always enabled.astro dev pytest --args and astro dev pytest --build-secrets could fail.Release date: January 24, 2024
Use the new --build-secrets flag with the following commands to mount a secret value to an Astro project image:
astro deployastro dev parseastro dev pytestastro dev restartastro dev startastro dev upgrade testThis flag is equivalent to running docker build --secret for your Astro Runtime image build. Use this flag to simplify build steps for customizing the Astro Runtime image, for example when you need to install Python packages from a private source .
Release date: December 4, 2023
You can use the new astro deploy --image command to deploy only the image to you Deployment. Previously, you could either complete a full code deploy with astro deploy or only update your dags with a dag-only deploy. See Trigger an image-only deploy for more information.
Release date: November 8, 2023
astro deployment airflow-variable, astro deployment connection, and astro deployment pool commands were returning the error failed to decode response from API.Release date: November 7, 2023
astro workspace users list occasionally failed to return a table.Release date: November 1, 2023
dags folder to Astro. To remove this warning along with all other CLI warnings, run astro config set show_warnings false.astro deployment create sometimes showed an invalid Runtime version error for valid Runtime versions.Release date: October 12, 2023
test/dags/test_dag_integrity.py was renamed to test/dags/test_dag_example.py to highlight that this test is an example.Release date: September 14, 2023
astro dev upgrade-test, the generated HTML report for dag tests now shows how many dags passed and failed the test.astro deploy was not formatted properly.astro dev upgrade-test would occasionally output that it was testing an upgrade to the latest version of Astro Runtime, even if it wasn’t.astro dev upgrade-test didn’t produce an HTML report for dag tests.Release date: August 30, 2023
astro dev parse or astro deploy, resulting in a command execution failure.Release date: August 29, 2023
WORKSPACE_AUTHOR role.astro deployment inspect now shows you a Deployment’s workload identity.astro deploy when dag-only deploys are enabled.astro dev pytest would incorrectly fail when testing an Astro project within a CI/CD process.Release date: August 10, 2023
astro deployment create on Astro Hosted would create Deployments where dag-only deploys were turned off by default.Release date: August 4, 2023
astro run didn’t work properly.Release date: August 3, 2023
You can use the new astro dev upgrade-test command to anticipate and address problems before upgrading to a newer version of Astro Runtime. The command runs several test which let you determine whether an upgrade will result in major dependency changes and import errors, allowing you to fix the problems before you upgrade. See Test your Astro project locally for more information.
--description flag with astro deploy to add a description for your deploy. You can use this description to let other users know why you made a deploy or what changes a deploy contains.--role flag with astro organization team create/update to update a Team’s Organization-level role.--execution-date flag with astro run to trigger a dag run for a specific execution date.--verbose flag with astro run to stream all logs to your terminal after the dag run triggers.astro deployment inspect was showing the wrong value for a Deployment’s workload identity on Astro Hosted.astro dev restart would occasionally not work.Release date: July 12, 2023
Release date: July 6, 2023
You can now manage Organization API tokens using the following CLI commands:
astro organization token createastro organization token rolesastro organization token listastro organization token updateastro organization token rotateastro organization token deleteYou can now use the following commands to download resources from the Astronomer Registry:
astro registry dag addastro registry provider addThe Astro registry contains dags and provider packages that are ready to use out of the box. Use these commands to quickly add resources to an Astro project, which you can then run locally or on Astro.
worker_concurrency to 0 in a Deployment file.Release date: June 30, 2023
isHighAvailability and CICDEnforcement fields in Deployment files were not processed correctly.Release date: June 13, 2023
You can now manage Astro Teams using the following CLI commands:
astro workspace team addastro workspace team listastro workspace team updateastro workspace team removeastro organization team createastro organization team listastro organization team updateastro organization team deleteastro organization team user removeastro organization team user addastro organization team user listYou can use these commands in automated workflows with Workspace API tokens and Organization API tokens.
You can now manage Workspace API tokens using the following CLI commands:
astro workspace token createastro workspace token addastro workspace token listastro workspace token updateastro workspace token rotateastro workspace token deleteThese commands can be used to manage API tokens as part of an automated workflow.
--cluster-type "dedicated" flag when using astro deployment create to create a Deployment on a dedicated cluster in Astro Hosted.astro deployment inspect.--enforce-cicd flag with astro deployment create and astro deployment update to enforce CI/CD on a given Deployment.Release date: May 19, 2023
Release date: May 18, 2023
Use the following new Astro CLI commands to manage your Airflow variables, pools, connections, on Astro Deployments. These commands are particularly useful for automating the creation of new Deployments based on old ones, as you can now transfer all Airflow resources from a source Deployment to a target Deployment:
astro deployment connection listastro deployment connection createastro deployment connection updateastro deployment connection copyastro deployment airflow-variable listastro deployment airflow-variable createastro deployment airflow-variable updateastro deployment airflow-variable copyastro deployment pool listastro deployment pool createastro deployment pool updateastro deployment pool copy--args flag to specify pytest arguments to run with astro dev pytest. For example, you can run astro dev pytest --args "-p pytest_cov" to plugin the pytest_cov plugin with your pyests.ASTRO_API_TOKEN in the environment where you run the Astro CLI.astro dev object export --compose. After you modify the file, you can use it to start your project with astro dev start --compose-file <compose-file-location>.postgres.repository and postgres.tag with astro config set. You can use these configurations to customize the postgres database used in your local Airflow environments.astro user invite has been deprecated.astro deployment variable create/update was not producing error when it failed to create an environment variable.Release date: April 20, 2023
astro workspace user list didn’t work when using a Workspace API token.Release date: April 19, 2023
You can now manage Astro Workspaces from the Astro CLI using the following new commands:
To automate Workspace management, you can run these commands using a Workspace API token.
Release date: April 11, 2023
dags folder to .dockerignore whenever an image build was interrupted, resulting in dags not being deployed on the next image build.Release date: March 30, 2023
astro user invite will be deprecated in Astro CLI v1.15.0. Any use of this command in your projects or automation needs to be updated to astro organization user invite before Astro CLI v1.15.0 is released.--clean-output for Deployment commandsYou can now use the -—clean-output flag with the following commands to make sure that any output comes only from the command itself.
astro deployment inspectastro deployment createastro deployment updateThis is helpful for users automating actions with deployment files, like using the Deploy Action template with Github Actions.
ASTRO_HOMEThe new environment variable ASTRO_HOME allows you to change the directory where the Astro CLI stores its global config file. This can be useful in environments where the CLI doesn’t have access to the HOME directory.
astro login won’t ask for email input in the command line anymore. You can now provide your email address in the browser when you log in.Release date: March 22, 2023
Release date: March 22, 2023
You can now expose your local Airflow webserver and postgres database to all networks you’re connected to using the following command:
When you trigger a dag deploy to Astro, the CLI now includes the name of the dag bundle version that it pushed. You can use this name to verify that your Deployment uses the correct version of your dags after a deploy.
If you add the environment variable ASTRO_API_TOKEN=<workspace-api-token> to your environment, the Astro CLI will use the specified Workspace API token to perform Workspace and Deployment actions without requiring you to log in.
You can now disable astro run commands and exclude astro-run-dag from any images built by the CLI using the following command:
In new Astro projects, requirements.txt now includes a commented list of the pre-installed provider packages on Astro Runtime.
os.getenv(key,default).Release date: February 27, 2023
You can now configure the Astro CLI to run Airflow locally and deploy to Astro using Podman. Podman is an alternative container engine to Docker that doesn’t require root access and orchestrates containers without using a centralized daemon.
To configure the Astro CLI to use Podman, see Run the Astro CLI using Podman.
astro logout.astro deploy would not return an error when you specified a Deployment name that didn’t exist.Release date: February 2, 2023
To help you manage users in your Organization, Astro CLI 1.10.0 includes the following new commands:
astro organization user invite: Invite a new user to your Astronomer Organization.astro organization user update: Update a user’s Organization role.astro organization user list: List all users in your Organization.astro workspace user add: Add a user to a Workspace.astro workspace user update: Update a user’s role in a Workspace.astro workspace user list: List all users in a Workspace.astro workspace user remove: Remove a user from a Workspace.astro organization user invite is identical to the existing astro user invite command. astro user invite will be deprecated in a future release.For more information, see the astro organization and astro workspace command references.
Release date: January 13, 2023
Astro CLI version 1.9 includes three new commands that make it possible to programmatically create and update Deployments:
astro deployment inspect --template: Create a template file in YAML for an existing Deployment. This template file includes all information about the Deployment in its current state, including worker queue configurations, environment variables, and Astro Runtime version.astro deployment create --deployment-file: Create a new Deployment with the configurations specified in a template file.astro deployment update --deployment-file: Update an existing Deployment based on the values in a Deployment file.You can use template and Deployment files to define Astro Deployments as code. For example, if your team regularly creates and deletes Deployments for testing, you can use template files to avoid manually copying configurations in the Astro UI. For more information, see Astro CLI command reference.
--dag-file flag for astro runBy default, the astro run command parses all of the dags in your dags directory even if you are only running one dag.
In Astro CLI 1.9, you can instead use the --dag-file flag to run a specific dag file without parsing all other dags in your directory. Specifying an individual dag file makes it easier to troubleshoot errors for that dag and results in faster execution of the command.
astro config set -g upgrade_message false.Release date: December 12, 2022
__pycache__/ directory is now included in the .gitignore file of an Astro project by default. __pycache__/ includes compiled versions of dag and Python files that are automatically generated and should not be committed to Git.astro deployment update --dag-deploy enable and dag-only deploys were already enabled for the Deployment.sql_alchemy_conn]) in local Airflow environments. Now, users running Airflow 2.3 or above do not see deprecation warnings for SQLAlchemy in logs for locally running Airflow components.Release date: November 28, 2022
astro login.astro runastro run could not locate airflow_settings.yaml when running a local Airflow environment.astro dev object export was not compatible with astro run.Release date: November 23, 2022
astro deploy if you did not have an .env file in your Astro project.Release date: November 23, 2022
astro run commandYou can now use the astro run command to run and debug a dag from the command line without starting a local Airflow environment. When you run the command, the CLI compiles your dag and runs it in a single Airflow worker container based on your Astro project configurations. You can see task success or failure, as well as task logs, directly in your terminal.
This command is an alternative to running astro dev restart every time you make a change to your dag. Running dags without a scheduler or webserver improves the speed at which you can develop and test data pipelines.
To learn more, see Test your Astro project locally.
astro deploy with an empty dags folder, the CLI excludes your dags folder when building and pushing an image of your project to Astro. This lets you manage your dags and project files in separate repositories when using dag-only deploys.deployment inspect command now includes a dag-deploy-enabled field, and the fields are now ordered in logical groupings instead of by alphabetical order.docker-compose.override.yaml file of an Astro project were not properly applied.astro login didn’t recognize some valid domains.Release date: November 9, 2022
astro deploy -—dagsUse astro deploy -—dags with the Astro CLI to push only the dags directory of your Astro project to a Deployment on Astro. This is an additional option to astro deploy, which pushes all files in your Astro project every time you deploy your code to Astro.
Deploying only dags:
astro deploy when you only make changes to the dags directory.When you make changes to other files in your Astro project that aren’t in the dags directory, the astro deploy command is still required.
To use this feature, you must enable it for each Deployment. See Deploy dags only. For example CI/CD workflows with this feature enabled, see CI/CD.
astro deployment inspect commandYou can now run astro deployment inspect to return a Deployment’s current state and configuration as a JSON or YAML object. This includes worker queue settings, Astro Runtime version, and more. Use this command to quickly understand the state of your Deployment as code and as an alternative to viewing it in the Astro UI.
For more information, see the CLI command reference.
astro dev parse and astro dev pytest commands have improved legibility by no longer including Docker container logs.astro organization switch command now includes a -—login-link flag that you can use to manually log in if you don’t have access to a web browser.astro organization switch.astro dev start now times out if the Airflow webserver does not become healthy within a set period of time. Use the -—wait flag to specify a wait time in seconds or minutes.astro deploy with colima was failing due to an issue with registry authenticationastro deployment list didn’t display the Workspace ID for a DeploymentRelease date: November 3, 2022
interactive=true in your CLI configuration resulted in a 502 error.Release date: September 28, 2022
You can use the new astro dev object commands to better manage Airflow connections, variables, and pools between your local testing environment and Astro Deployments.
astro dev object import imports connections, variables, and pools from your Astro project airflow_settings.yaml into your locally running Airflow environment.astro dev object export exports connections, variables, and pools from your local airflow database to a file of your choosing. specify the --env-export flag to export Airflow connections and variables to your .env file as Astro environment variables.These commands enable you to:
You can now manage create, delete, and update worker queues on an Astro Deployment with the following new commands:
astro deployment worker-queue create creates a new worker queue in a Deployment.astro deployment worker-queue update updates an existing worker queue.astro deployment worker-queue delete deletes an existing worker queue.If you belong to multiple Astro Organizations, you can now use the CLI to switch between your Organizations:
astro organization list lists all Organizations you belong toastro organization switch allows you to switch between OrganizationsTo use these commands, you must be authenticated to your primary Organization through the CLI.
.exe file.conn_extra field of airflow_settings.yaml as YAML blocks instead of stringified JSON objects.--settings-file flag with astro dev start to load and update Airflow objects in your environment from the configuration file of your choosing.Release date: September 23, 2022
Release date: September 2, 2022
--deployment-name flag with all astro deployment commands to specify a Deployment by its name instead of its Deployment ID.--wait flag with astro deployment create to have the command wait until the new Deployment is healthy before completing.--no-browser flag with astro dev start if you don’t want the Airflow UI to automatically open in a new tab on your browser when you run the command.astro dev restart command no longer opens a new tab in your browser for the Airflow UI. When you use this command to apply changes to your dags, the Airflow UI should already be open.astro deployment variable create --load.Release date: August 18, 2022
You can now run bash commands in any locally running Airflow container using astro dev bash. You can use this to:
postgres command.For more information, see the CLI command reference.
You can invite new users to an Astro Organization with the new astro user invite command. Previously, you could only invite users to Astro with the Astro UI.
For more information, see the CLI command reference.
astro deployment variable create and astro deployment variable update. For example, astro deployment variable create KEY1=VAL1 KEY2=VAL2 creates variables for KEY1 and KEY2. You can still create environment variables from a file with the --load flag.astro dev start. Previously, the CLI showed an error and forced users to manually start Docker. Note that this feature only works on Mac OS.astro dev start as soon as the Airflow webserver is ready. Previously, you had to wait for the webserver to be ready and manually open or refresh your web browswer.Release date: July 19, 2022
--image-name flagYou can now deploy your Astro project with a custom Docker image by running astro deploy --image-name <custom-image>, as long as the image is based on Astro Runtime and is available in a local Docker registry. Customizing your Runtime image lets you securely mount additional files and arguments in your project, which is required for setups such as installing Python packages from private sources.
Using this flag, you can automate deploying custom Runtime images from a CI/CD pipeline. You can also separate your build and deploy workflows in different pipelines.
The --image-name flag is also available for the following local development commands:
astro dev startastro dev restartastro dev parseastro dev pytestFor more information about this command, see the CLI command reference.
Astro CLI users can now log into Astro on a machine that does not have access to a browser by running astro login --token-login. This is an alternative to astro login, which automatically opens the Astro UI in a browser on your machine.
If you run the command with this flag, the CLI provides a link to the Astro UI that you can manually open in a web browser. You then copy an authentication token from the UI and enter it in the CLI. If you’re using a browserless machine with the Astro CLI, this enables you to log in. For a browserless login, you can open the link and copy the token on a separate machine from the one running the Astro CLI.
For more information about this command, see the CLI command reference.
By default, astro deploy automatically parses the dags in your Astro project for syntax and import errors. To develop more quickly, you can now configure the Astro CLI to automatically skip parsing dags before a deploy by updating one of the following configurations:
skip_parse: true to your .astro/config.yaml file.ASTRONOMER_SKIP_PARSE=true as an environment variable to your local environment or CI/CD pipeline.For more information on parsing dags, see Test your Astro project locally. For more information about deploying to Astro, see Deploy code.
astro dev parse failed on dags using the SnowflakeOperator. If you use the SnowflakeOperator, delete .astro/test_dag_integrity_default.py from the tests directory of your Astro project and run astro dev init with the Astro CLI. This command will create a new file in your project that does not have this issue.Release date: June 28, 2022
astro deploy would kill a running projectRelease date: June 13, 2022
You can now run the following commands with a Deployment API key:
astro deployastro deployment listastro deployment logsastro deployment updateastro deployment deleteastro deployment variable listastro deployment variable createastro deployment variable updatePreviously, you could run only the astro deploy command with a Deployment API key. For more information on API keys.
The Astro CLI now follows a new process to determine which Deployment to run a command against. Specifically:
astro deployment update <deployment-id>../astro/config.yaml file of your Astro project. In this file, you can set up to one Deployment ID as default. This is an alternative to manually specifying it or using a Deployment API key.These changes make it easier to run and automate Deployment-level commands with the Astro CLI. Most notably, it means that you no longer need to specify a Deployment ID in cases where it can be automatically implied by our system.
If your CI/CD pipelines currently define one or more Deployment IDs, you may remove those IDs and their corresponding environment variables as they are no longer required. For up-to-date CI/CD templates, see Automate code deploys with CI/CD.
Release date: June 6, 2022
astro deploy, astro dev parse, and astro dev pytest failed for some usersRelease date: June 2, 2022
The Astro CLI is now a single CLI executable built for all Astronomer products. This new generation of the CLI optimizes for a consistent local experience with Astro Runtime as well as the ability to more easily upgrade to Astro from other products hosted on Astronomer.
To establish a shared framework between products, the Astro CLI now uses a single astro executable:
Additionally, some commands have been standardized so that they can be shared between Astro and Astronomer Software users. As part of this change, astro auth login and astro auth logout have been renamed astro login and astro logout:
For Astro users, these are the only changes to existing CLI functionality. All other commands will continue to work as expected. We strongly recommend that all users upgrade.
You can now use astro config get and astro config set to retrieve and modify the configuration of your Astro project as defined in the .astro/config.yaml file. The configuration in this file contains details about how your project runs in a local Airflow environment, including your Postgres username and password, your webserver port, and your project name.
For more information about these commands, see the CLI command reference.
You can now use astro context list and astro context switch to show all the Astronomer contexts that you have access to and switch between them. An Astronomer context is defined as a base domain that you can use to access either Astro or an installation of Astronomer Software. A domain will appear as an available context if you have authenticated to it at least once.
This command is primarily for users who need to work in both Astro and Astronomer Software installations. If you’re an Astro user with no ties to Astronomer Software, ignore this command. For more information, see the CLI command reference .
For more information about these commands, see the CLI command reference .
--update flag has been removed from astro deployment variable create. To update existing environment variables for a given Deployment, use astro deployment variable update instead.astrocloud)Release date: April 28, 2022
A new astro deployment variable update command allows you to more easily update an existing environment variable by typing a new value directly into your command line or adding the updated variable to a .env file.
This command replaces the —update flag that was previously released with the astro deployment variable create command. For more information, see the Astro CLI command reference.
astro workspace switch, you can now specify a <workspace-id> as part of the command and avoid the prompt to manually select a Workspaceastro login. After you run that command once successfully, the Astro CLI will cache your email address in your config.yaml file and not prompt you to enter it againastro deploy and astro dev start commands will now inform you if there is a new version of Astro Runtime availableastro deployment variable create —load command would fail if the specified .env file had a comment (e.g. # <comment>) in itastrocloud)Release date: April 14, 2022
astro deployment variable create is a new Astro CLI command that allows you to create and update environment variables for a Deployment on Astro. New environment variables can be loaded from a file (e.g. .env) or specified as inputs to the CLI command itself. If you already set environment variables via a .env file locally, this command allows you to set environment variables on Astro from that file as well. More generally, this command makes it easy to automate creating or modifying environment variables instead of setting them manually in the Astro UI.
For more information about this command and its options, see the Astro CLI command reference.
You can now list existing environment variables for a given Deployment and save them to a local .env file with a new astro deployment variable list command. This command makes it easy to export existing environment variables for a given Deployment on Astro and test dags with them in a local Airflow environment.
For more information about this command and its options, see the Astro CLI command reference.
Dockerfile as long as the image is based on an existing Astro Runtime imageastrocloud)Release date: April 11, 2022
astro dev startastro deploy, the CLI now provides URLs for accessing the Deployment’s Cloud UI and Airflow UI pages.astrocloud)Release date: March 31, 2022
astro dev start command should now be ~30 seconds fasterastro dev parse results in an error, the error messages now specify which dags they apply totest_dag_integrity.py ), running them with astro dev pytest will now provide more information about which part of your code caused an errorastro dev parse/pytest would occasionally result in an “orphaned containers” warningastro dev parse/pytest would crash when parsing projects with a large number of dagsdocker-compose.override.yml files would cause astro dev parse/pytest to stop workingastrocloud)Release date: March 17, 2022
astro dev parse/pytest. If you are currently using Astro CLI 1.3.1, then we recommend upgrading to 1.3.2+ as soon as possible to receive important bug fixes.To better integrate with Astro’s identity-based login flow, the CLI now prompts you for your login email after you run astro login. Based on your email, the CLI assumes your Astro Organization and automatically brings you to your Organization’s login flow via web browser.
astro deploy now builds and tests only one image per deploy. This should result in improved deployment times in CI/CD pipelines which use this command.test directory generated by astro dev init now includes more example pytests.dev parse permission errors on WSL. To fully fix this issue for an Astro project, you must delete the project’s existing .astro directory and rerun astro dev init.astro dev parse/pytest while a local Airflow environment was running would crash the Airflow environment. This issue was introduced in Astro CLI 1.3.1, which is no longer available for download.astrocloud)Release date: March 3, 2022
astro dev parse is a new Astro CLI command that allows you to run a basic test against your Astro project to ensure that essential aspects of your code are properly formatted. 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.
This command was built to replace the need to constantly run astro dev restart during troubleshooting to see if your dags 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, we still recommend using astro dev pytest, which allows you to run other custom tests in your project.
For more information about astro dev parse, see the CLI command reference. For more guidance on testing dags locally, see Test dags locally.
astro deploy parses dags by defaultTo better protect your Deployments from unexpected errors, astro deploy now automatically applies tests from astro dev parse to your Astro project before completing the deploy process. If any of these tests fail, the CLI will not push your code to Astro.
For more information about astro deploy, see CLI command reference.
You can now use astro deployment update to update certain configurations for an existing Astro Deployment directly from the Astro CLI. The configurations that you can update are:
This is the same set of configurations that you can modify with the Edit Configuration view in the Astro UI. For more information on modifying a Deployment, see Deployment settings. For more information about this command, see CLI command reference.
astrocloud)Release date: February 25, 2022
You can now use Deployment API keys to run astro deploy either from the CLI directly or via a CI/CD script. This update simplifies deploying code to Astro via CI/CD.
With an existing Deployment API key, you can set ASTRONOMER_KEY_ID and ASTRONOMER_KEY_SECRET as OS-level environment variables. From there, you can now configure a CI/CD pipeline that:
astro deploy.When astro deploy is run, the CLI will now automatically look for and use the Deployment API key credentials that were set as environment variables to authorize and complete a code push.
Previously, any script that automated code pushes to Astro had to include a series of cURL requests to the Cloud API and could not use Deployment API keys to run an Astro CLI command. If your existing CI/CD pipelines still utilize this method, we recommend replacing those commands with an Astro CLI-based workflow. For more information and guiding examples, see CI/CD.
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 via astro dev init now include a tests directory, which includes one example pytest built by Astronomer.
When you run this command, the Astro CLI creates a local Python environment that includes your dag code, dependencies, and Astro Runtime Docker image. The CLI then runs any pytests in the tests directory and shows you the results of those tests in your terminal. You can add as many custom tests to this directory as you’d like.
For example, you can use this command to run tests that check for:
These tests don’t require a fully functional Airflow environment in order to execute, which makes this Astro CLI command the fastest and easiest way to test dags locally.
In addition to running tests locally, you can also run pytest as part of the Astro deploy process. To do so, specify the --pytest flag when running astro deploy. This ensures that your code push to Astro automatically fails if any dags do not pass all pytests specified in the tests directory of your Astro project. For more information, see Test your Astro project locally.
If you prefer to troubleshoot dags and monitor your Deployments from the command line, you can now run astro deployment logs, a new Astro CLI command that allows you to view the same scheduler logs that appear in the Logs tab of the Astro UI.
When you run this command, all scheduler logs emitted by a Deployment over the last 24 hours appear in your terminal. Similarly to the Astro UI, you can filter logs by log level using command flags. For more information about this command, see the CLI command reference.
You can now use the Astro CLI to create and delete Deployments on Astro with two new commands:
astro deployment createastro deployment deleteThese commands are functionally identical to the Deployment configuration and deletion process in the Astro UI. For more information, see the CLI command reference.
astrocloud)Release date: February 17, 2022
astro dev restart command to test local changesFor users making quick and continuous changes to an Astro project locally, the Astro CLI now supports a new astro dev restart command. This command makes local testing significantly easier and is equivalent to running astro dev stop followed by astro dev start.
The Astro CLI now supports the Apache Airflow triggerer component in a local environment. This means that you can test dags that use deferrable operators locally before pushing them to a Deployment on Astronomer. Additionally, triggerer logs appear alongside webserver and scheduler logs when you run astro dev logs.
The triggerer will only be created in local environments running Astro Runtime 4.0.0+.
astrocloud)Release date: February 3, 2022
The Astro CLI (astrocloud) is now generally available as the official command-line tool for Astro. It is a direct replacement of the previously released ./astro executable.
The Astro CLI sets the foundation for more robust functionality in the future and includes several significant improvements to both the local development experience as well as use cases specific to Astro. These changes are summarized in the following sections.
The Astro CLI can be installed via Homebrew. Commands take the form of:
We strongly recommend that all users install the Astro CLI and delete the ./astro executable from local directories as soon as possible. For guidelines, read Install the Astro CLI. As of February 2022, ./astro will no longer be maintained by our team. With that said, the release of the Astro CLI does not have any impact on your existing Deployments or dags.
The Astro CLI introduces an easy way to authenticate. Instead of requiring that users manually pass authentication tokens, the new CLI consists of a simple, browser-based login process.
Built with refresh tokens, the Astro CLI also does not require that users re-authenticate every 24 hours, as was the case with ./astro. As long as you remain authenticated via the Astro UI, your session via the Astro CLI will remain valid. You can expect to be asked to re-authenticate only once every few months instead of on a daily basis.
Astro CLI 1.0.0 includes several improvements to the local development experience:
astrocloud dev start with Docker Buildkit enabled. This resolves a common issue where users with Docker Buildkit enabled could not run this command.astrocloud dev start, the CLI no shows you the status of the webserver container as it spins up on your local machine. This makes it easier to know whether the Airflow UI is unavailable because the Airflow webserver container is still spinning up.astrocloud deploy now shows a list of your Deployments in the order by which they were created instead of at random../astro)Release date: December 9, 2021
The Astro CLI is built to enable developers to learn about, test, automate, and make the most of Apache Airflow both locally and on Astro. To that end, we’ve updated the CLI with two example dags that will be present for all users in the /dags folder that is automatically generated by astro dev init.
The file names are:
example-dag-basic.pyexample-dag-advanced.pyThe basic dag showcases a simple ETL data pipeline and the advanced dag showcases a series of more powerful Airflow features, including the TaskFlow API, jinja templating, branching and more. Both dags can be deleted at any time.
Fixed a broken documentation link and outdated description in the airflow_settings.yaml file, which you can use to programmatically set Airflow connections, variables, and pools locally.
./astro)Release date: November 5, 2021
Failed to verify remote log exists s3:///)../astro)Release date: October 25, 2021
./astro)Release date: October 15, 2021
./astro)Release date: September 28, 2021
./astro dev init now always pulls the latest version of Astro Runtime for new projects. This means that you no longer have to upgrade the CLI in order to take advantage of a new Runtime release. Note that you still need to manually upgrade Runtime for existing projects../astro)Release date: September 20, 2021
3.0.2./astro dev run to run Airflow CLI commands./astro dev logs to show logs for the Airflow scheduler and webserver when developing locally./astro)Release date: August 31, 2021
3.0.0./astro dev init now include a README file./astro)Release date: July 31, 2021
./astro)Release date: July 30, 2021
./astro login without specifying a domain (astronomer.io is always assumed).