> ## Documentation Index
> Fetch the complete documentation index at: https://astronomer.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Astro CLI release notes
[Subscribe to Astro CLI release notes](/docs/astro/release-notes-subscribe) to receive updates via RSS, email, or Slack.
This document provides a summary of all changes made to the [Astro CLI](/docs/cli/v1.40/overview). For general product release notes, go to [Astro Release Notes](/docs/astro/release-notes). If you have any questions or a bug to report, contact [Astronomer support](https://cloud.astronomer.io/open-support-request).
* **Stable versions**: 1.40.1, 1.39.0, and 1.38.1. See [Astro CLI release and lifecycle policy](/docs/cli/v1.40/release-lifecycle-policy) for more information about support for CLI versions.
### Bug fixes
* Fixed the `astro dev pytest` command to use `docker cp` instead of bind-mounts for copying test files into the container.
### New `astro dev build` command
A new [`astro dev build`](/docs/cli/v1.40/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.
### New `astro api` command
A new [`astro api`](/docs/cli/v1.40/astro-api) command lets you make authenticated API requests to Astronomer services directly from the Astro CLI:
* [`astro api airflow`](/docs/cli/v1.40/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`](/docs/cli/v1.40/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`.
### Standalone mode for Docker-free local development
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:
```bash wrap theme={null}
astro config set dev.mode standalone
```
Or use the `--standalone` flag to override for a single command:
```bash wrap theme={null}
astro dev start --standalone
```
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.
### Built-in reverse proxy for multi-instance local development
When you run `astro dev start`, a built-in reverse proxy now routes `.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`](/docs/cli/v1.40/astro-dev-proxy). 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: `..localhost:6563`.
### New `astro telemetry` command
A new [`astro telemetry`](/docs/cli/v1.40/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`](/docs/cli/v1.40/astro-telemetry-disable) or set the `ASTRO_TELEMETRY_DISABLED` environment variable to `1` to opt out.
### Removed `astro registry` command
The `astro registry` command and its subcommands (`dag add`, `provider add`) have been removed.
### Additional improvements
* Added the `--kill` (`-k`) flag to [`astro dev restart`](/docs/cli/v1.40/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`.
* Added the `--fix` flag to [`astro dev upgrade-test`](/docs/cli/v1.40/astro-dev-upgrade-test) to automatically fix linting issues identified by the upgrade test using ruff.
* Added the `--no-dags-base-dir` flag to [`astro deploy`](/docs/cli/v1.40/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.
* Added `--api-server` and `--dag-processor` component filter flags to [`astro dev logs`](/docs/cli/v1.40/astro-dev-logs).
* Astro IDE commands now display Workspace and project names instead of IDs in command output.
* Fixed an issue that prevented organization switching by ID when the organization didn't appear in the initial paginated list.
* Fixed Podman builds by passing the machine socket through correctly.
### Additional improvements
* The Astro CLI now strips newline characters from entries in the dag integrity exceptions file, preventing parse failures caused by trailing newlines.
* You can now use the `--session-id` flag with [`astro ide project import`](/docs/cli/v1.43/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.
* Added support for Astro Private Cloud 1.1.
### Additional improvements
* You can now import Astro IDE projects to non-empty directories with user confirmation.
### Bug fixes
* Fixed `astro remote deploy` to correctly install dependencies from `requirements-client.txt` and `packages-client.txt` during image build.
**Known issue (resolved in 1.38.1)**
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.
### Enable remote execution with `astro dev init`
You can now create a remote execution project using [`astro dev init`](/docs/cli/v1.43/astro-dev-init#remote-execution-mode). Setting remote execution mode prompts you to add the resources necessary for configuring your remote execution configuration.
### Behavior Changes
These changes only apply to Astro users. Please check the [CLI command reference](/docs/cli/v1.43/reference) for more information about CLI commands for Astro Private Cloud.
* Enabled `astro remote deploy` command by default
* Deprecated `--force-upgrade-to-af3` flag from `astro deploy`
* Added `--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.
### Support for Astro Private Cloud 1.0
Added support for [Astro Private Cloud 1.0](/docs/astro-private-cloud/v-1-x/astro-private-cloud-overview), including the ability to push images and dags to separate data plane clusters.
### Additional improvements
* The Deployment `get`, `list`, and `update` commands now display a new `REMOTE EXECUTION` column that indicates if Remote Execution is enabled for a Deployment.
* References to **Astronomer Software** have been updated to **Astro Private Cloud** in the CLI and documentation.
* A new `--workspace-id` flag has been added to `organization switch` for selecting a Workspace programmatically.
### Bug fixes
* Update Airflow client to update `default_pool` correctly by sending only slots and `include_deferred` with an `update_mask`.
* Ignore hidden files during Astro IDE project export.
### New Astro IDE commands
**Preview**
This feature is in [Preview](/docs/astro/feature-previews).
Added the following commands so that you can work with the [Astro IDE](/docs/astro/ide-overview) from the Astro CLI:
* [`astro ide project export`](/docs/cli/v1.40/astro-ide-project-export): Export your current local project to Astro IDE.
* [`astro ide project import`](/docs/cli/v1.40/astro-ide-project-import): Import an existing Astro IDE project into your local environment for development or editing.
* [`astro ide project list`](/docs/cli/v1.40/astro-ide-project-list): List all Astro IDE projects you have access to.
### Additional improvements
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.
### Bug fixes
* Fixed an issue where the CLI would silently not load connections from the specified Astro Deployment or Workspace if the settings file was missing. The CLI now loads Astro connections regardless of whether the settings file, default `airflow_settings.yaml`, is present.
### Improved Airflow 3 support
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.
#### New flags for `astro deployment create` and `astro deployment update`
You 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.
### Behavior changes
* Astro CLI 1.35.1 removes support for pools in Airflow Versions 2.6 and below. Airflow 2.6 corresponds to Runtime Version 8, which has reached end of maintenance date.
* Astro CLI 1.35.1 now interprets `--webserver` as `--apiserver` for Airflow 3 environments to reflect the updated component architecture.
### Restricted release
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](/docs/cli/v1.43/release-lifecycle-policy) for more information about different release channels and a list of restricted CLI versions.
### Additional improvements
* Updated the `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.
* Improved project linting.
* Updated linting in `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.
### Airflow 3 support
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](/docs/astro/airflow3/upgrade-af3) for steps to upgrade your Astro project from Airflow 2 to Airflow 3.
### Bug fixes
* Fixed an issue where the appropriate container engine for Airflow objects commands was not being used. Now, logic is in place to dynamically select Docker or Podman for Airflow object handling.
### Bug fixes
* Software users pulling images from internal registries no longer see a warning when their Astro Project’s Dockerfile path differs from the public defaults.
### Bug fixes
* Logs for `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.
### New flags for [`astro deploy`](/docs/cli/v1.43/astro-deploy) on Astronomer Software
You can now use the `--image` flag with `astro deploy` to trigger an image-only deploy on [Astronomer Software](/docs/cli/v1.43/astro-deploy).
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.
### Orbstack Container Runtime Engine Support for Mac
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.
### Additional improvements
* Introduced a new configuration option [`sha_as_tag`](/docs/cli/v1.43/configure-cli) 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.
### Bug fixes
* Fixed an issue where `deployments list --all` would not work on Astronomer Software.
### Additional improvements
* Dag-only and dbt deploys now use gzip compression for tar bundles, significantly reducing deploy times for large bundles to cloud Deployments.
### Astro CLI now includes pre-configured Podman container runtime
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](/docs/cli/v1.43/install-cli).
### Additional improvements
* You can now specify the project name as an optional positional argument in [`astro dev init`](/docs/cli/v1.40/astro-dev-init), simplifying project initialization by automatically creating and initializing a new directory.
### Behavior changes
* Previously in the CLI configuration file, the `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`](/docs/cli/v1.43/switch-container-management).
### New `--from-template` flag to setup template based project
You 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`](/docs/cli/v1.40/astro-dev-init) and the CLI sets up an Astro project based on the provided template.
### New `--show-workload-identity` flag to fetch workload identity of Deployment
You can now fetch the [workload identity](/docs/astro/authorize-deployments-to-your-cloud#what-is-workload-identity) value of a Deployment with the `--show-workload-identity` flag for [`astro deployment inspect`](/docs/cli/v1.40/astro-deployment-inspect).
### Additional improvements
* Added the ability for the CLI to autodetect the container runtime binary to use for the commands that utilize containers.
* Streamlined the behavior of `astro dev start` for Podman users.
### Behavior changes
* You no longer need to explicitly set Podman as your container management engine for the Astro CLI when you are configuring the Astro CLI to use Podman, as the CLI now autodetects the container runtime binary to use for the commands that use containers.
### Bug fixes
* Fixed an issue where Astro created all the worker queues with the configuration of the first queue in the list when using the Deployment config file to create or update a Deployment.
### New description flag for deploy on Astronomer Software
You can now add custom deploy descriptions during the [`astro deploy`](/docs/cli/v1.43/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 deployment create` to create in Azure by default for Astro
**Breaking Change**
Azure is now the default cloud provider when creating a deployment on Astro with the [`astro deployment create`](/docs/cli/v1.40/astro-deployment-create) CLI command.
Use the `--cloud-provider` flag to specify `aws`, `gcp`, or `azure` as the cloud provider for the Deployment.
### Additional improvements
* You can now create Astro Hosted Deployments on Azure via Astro CLI.
### New flags for create and update Deployments
* You can now add Extra Large schedulers to your Deployments when you create or update them with the new `extra_large` option for the `--scheduler` flag. This requires a minimum Astro Runtime version of 9.7.0.
* You can also customize the workload identity when updating (AWS and GCP Hosted only) or creating (AWS Hosted only) Deployments directly with the command line with the `--workload-identity` flag or by adding it to the Deployment config file with the `workload_identity` field.
See [`astro deployment create`](/docs/cli/v1.43/astro-deployment-create) and [`astro deployment update`](/docs/cli/v1.43/astro-deployment-update) for more information.
### Bug fixes
* Fixed a bug where the CLI ignored files when bundling dags for code deploys.
### Work with dbt projects on Astro
**Labs**
This feature is in [Labs](/docs/astro/feature-previews). Reach out to 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:
* [astro dbt deploy](/docs/cli/v1.43/astro-dbt-deploy)
* [astro dbt delete](/docs/cli/v1.43/astro-dbt-delete)
### Additional improvements
* Added the ability to switch Workspaces by using the Workspace name instead of the `workspace-id`. See [astro workspace switch](/docs/cli/v1.43/astro-workspace-switch).
### Bug fixes
* Fixed a bug where the command `astro deployment inspect --key configuration.is_development_mode` was printing wrong the value.
### Bug fixes
* Fixed an issue where the API token expiration check was causing login failures with API tokens that did not have an expiration date.
### New flags for the Deployment logs commands:
You can now filter logs for specific Deployment components using the following new flags for `astro deployment logs`:
* `--webserver`
* `--scheduler`
* `--triggerer`
* `--worker`
### Exclude dag files from parse test
You 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.
### Additional improvements
* Astro projects no longer have to include dags in order to run `astro deploy --image`.
* You can now append `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.
* You can now use the `--development-mode disable` flag with `astro deployment update` to turn off [development mode](https://docs.astronomer.io/astro/deployment-resources#hibernate-a-development-deployment) for an existing Deployment. Note that you still cannot turn on development mode for an existing Deployment.
### Bug fixes
* Fixed an issue where you couldn't create two Deployments with identical names across different Workspaces.
* The `upgrade-test` command now returns the correct error code, ensuring accurate feedback during testing and CI/CD.
### New commands to assign Organization and Workspace API tokens at different levels
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-token`](/docs/cli/v1.43/astro-deployment-token-organization-token)
* [`astro deployment token workspace-token`](/docs/cli/v1.43/astro-deployment-token-workspace-token)
* [`astro workspace token organization-token`](/docs/cli/v1.43/astro-workspace-token-organization-token)
For more information about this feature, see:
* [Assign an Organization or Workspace API token to a Deployment](/docs/astro/deployment-api-tokens#assign-an-organization-or-workspace-api-token-to-a-deployment).
* [Assign an Organization API token to a Workspace](/docs/astro/workspace-api-tokens#assign-an-organization-api-token-to-a-workspace)
### Bug fixes
* Fixed an issue where existing secret environment variables in a Deployment file could be applied to the Deployment with an empty value. The secret variable value now persists.
* Fixed an issue where `astro deployment inspect` generated an incorrect Airflow API URL.
* Fixed a bug that caused some input checks for `astro deployment upgrade-checks` to fail against valid inputs.
### Manage Deployment API tokens with the Astro CLI
You can now manage [Deployment API tokens](/docs/astro/deployment-api-tokens) using the following CLI commands:
* `astro deployment token create`
* `astro deployment token list`
* `astro deployment token update`
* `astro deployment token rotate`
* `astro deployment token delete`
### Additional improvements
* Updated the example dags that the Astro CLI creates when you run `astro dev init`.
* The CLI now tells you if your API token is invalid.
### Bug fixes
* Fixed an issue with `deployment variable create` where it would cut off the new variables value at the first "=" character.
* Fixed an issue where running a deployment command in a workspace without a deployment caused an error. Now users will be asked if they want to create a deployment if one does not exist.
* Fixed an issue where `astro dev start —deployment-id` was not creating local connections correctly in some scenarios.
* Fixed an issue where `astro deployment` commands could only list 20 deployments. Now the commands will list up to 1000 for each workspace.
### Bug fixes
* Fixed an issue where the Astro CLI would experience a code panic if you tried to set a hibernation schedule for a Deployment that didn't exist.
* Fixed an issue where the Astro CLI would send and retrieve hibernation schedules for non-development Deployments.
### Support for hibernating development Deployments
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](/docs/cli/v1.40/astro-deployment-create).
Use the following new commands to hibernate development Deployments regardless of their existing hibernation schedule:
* [`astro deployment hibernate`](/docs/cli/v1.43/astro-deployment-hibernate)
* [`astro deployment wake-up`](/docs/cli/v1.43/astro-deployment-wake-up)
Additionally, you can create new development Deployments and configure long-term hibernation schedules for them using `astro deployment create`.
### Additional improvements
* You can now configure a custom workload identity when you create a Deployment using a Deployment file.
* Added support for the upcoming custom role management feature on Astro
### Bug fixes
* Fixed an issue where `astro deployment variable list --save` didn't format secret environment variables correctly.
* Fixed an issue where you couldn't update a Deployment with a Deployment file using a Deployment API token.
### Changes to existing CLI command flags
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`.
### Kubernetes worker configurations are now consistent with the Astro Cloud UI
You can now use Deployment files or the Astro CLI to create or update Kubernetes worker configurations.
[Deployment files](/docs/astro/deployment-file-reference) 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 create`
* `astro deployment worker-queue update`
Instead, 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`](/docs/cli/v1.40/astro-deployment-create) and [`astro deployment update`](/docs/cli/v1.40/astro-deployment-update) to edit your Kubernetes worker configuration using the Astro CLI.
### Changes to Deployment file configurations
The following changes have been made to the format of [Deployment files](/docs/astro/deployment-file-reference):
* You no longer have to specify a `cluster_name` for standard Deployment files.
* `scheduler_size` is no longer case sensitive.
* Possible values for `cloud_provider` are now `gcp`, `aws`, and `azure`. This input is not case sensitive.
* Possible values for `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 sensitive
* Possible values for the `executor` field are now include `celery` and `kubernetes`. `CeleryExecutor` and `KubernetesExecutor` still work. This input is not case sensitive, so, for example, `celeryexecutor` still works.
* (*Astro Hosted only*) `default_task_pod_cpu`, `default_task_pod_memory`, `resource_quota_cpu`, and `resource_quota_memory` are new fields for Astro Hosted deployments.
* (*Astro Hybrid only*)`default_worker_type` is a new field for Hybrid deployments that use the Kubernetes executor.
### Additional improvements
* You can now trigger a dag-only deploy on Astronomer Software using `astro deploy --dags`. See [Deploy dags on Astronomer Software](https://www.astronomer.io/docs/software/deploy-dags).
* `astro deployment logs --key-word` is a new flag that allows you to search your audit logs for an exact key word or phrase.
* If you log in to Astro from the CLI, you need to select a Deployment when you deploy code. Previously, the Astro CLI used auto-select to automatically choose a Deployment for code deploys based on the CLI context. Now, by default, the CLI does not auto-selects the Deployments where your code deploys when you use it. However there are the following exceptions:
* If you log in to Astro with an API token using the `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.
* There is a new config, `auto_select`. If `auto-select` is set to `true` in the config file, auto-select is always enabled.
### Bug fixes
* Fixed an issue where `astro dev pytest --args` and `astro dev pytest --build-secrets` could fail.
### New flag to mount secrets to Astro project image
Use the new `--build-secrets` flag with the following commands to mount a secret value to an Astro project image:
* `astro deploy`
* `astro dev parse`
* `astro dev pytest`
* `astro dev restart`
* `astro dev start`
* `astro dev upgrade test`
This flag is equivalent to running [`docker build --secret`](https://docs.docker.com/build/building/secrets/#secret-mounts) 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](/docs/cli/v1.43/private-python-packages?tab=pypi#install-python-packages-from-a-private-pypi-index) .
### New command to deploy only images
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](/docs/astro/deploy-dags#trigger-an-image-only-deploy) for more information.
### Bug fixes
* Fixed a bug so you can now use a deployment file to create a Kubernetes deployment with a custom worker queue.
### Bug fixes
* Fixed an issue where `astro deployment airflow-variable`, `astro deployment connection`, and `astro deployment pool` commands were returning the error `failed to decode response from API`.
### Bug fixes
* Fixed an issue where `astro workspace users list` occasionally failed to return a table.
* Fixed an issue introduced in version 1.19.4 where you could not deploy a custom image to Astro.
### Additional improvements
* The Astro CLI now shows a warning if you attempt to deploy a project with an empty `dags` folder to Astro. To remove this warning along with all other CLI warnings, run `astro config set show_warnings false`.
### Bug fixes
* Fixed an issue where `astro deployment create` sometimes showed an invalid Runtime version error for valid Runtime versions.
### Additional improvements
* Sample test `test/dags/test_dag_integrity.py` was renamed to `test/dags/test_dag_example.py` to highlight that this test is an example.
### Bug fixes
* Fixed an issue where CI/CD pipelines were unable to use Deployments as Code to create Deployment Previews for Deployments using the Kubernetes executor.
* Fixed an issue where the CLI was asking users to select from the wrong regions when creating a Deployment on an AWS cluster.
* Fixed an issue where secret variables values were being printed to local logs.
### Additional improvements
* When you run `astro dev upgrade-test`, the generated HTML report for dag tests now shows how many dags passed and failed the test.
### Bug fixes
* Fixed an issue where you couldn't create a Deployment on a dedicated cluster using a Deployment file and API token.
* Fixed an issue where the Deployment URL that appears after you run `astro deploy` was not formatted properly.
* Fixed an issue where `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.
* Fixed an issue where `astro dev upgrade-test` didn't produce an HTML report for dag tests.
### Bug fixes
* Fixed an issue where dags would fail to parse correctly when running `astro dev parse` or `astro deploy`, resulting in a command execution failure.
### Additional improvements
* You can now grant Astro users the `WORKSPACE_AUTHOR` role.
* You can now run an Astro project from the same directory an Apache Airflow project.
* `astro deployment inspect` now shows you a Deployment's workload identity.
### Bug fixes
* Fixed an issue where some dags could be missed during `astro deploy` when dag-only deploys are enabled.
* Fixed an issue where `astro dev pytest` would incorrectly fail when testing an Astro project within a CI/CD process.
* Fixed an issue where you couldn't update a Deployment on a standard cluster using a Deployment file.
### Bug fixes
* Fixed an issue where running `astro deployment create` on Astro Hosted would create Deployments where dag-only deploys were turned off by default.
### Bug fixes
* Fixed an issue where `astro run` didn't work properly.
### New command to test Astro projects before you upgrade
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](/docs/cli/v1.40/test-your-astro-project-locally) for more information.
### Additional improvements
* You can now specify the `--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.
* You can now specify the `--role` flag with `astro organization team create/update` to update a Team's Organization-level role.
* You can now specify the `--execution-date` flag with `astro run` to trigger a dag run for a specific execution date.
* You can now specify the `--verbose` flag with `astro run` to stream all logs to your terminal after the dag run triggers.
### Bug fixes
* Fixed an issue where `astro deployment inspect` was showing the wrong value for a Deployment’s workload identity on Astro Hosted.
* Fixed an issue were `astro dev restart` would occasionally not work.
### Bug fixes
* Fixed an issue were some Astro Hosted Deployment updates triggered by the Astro CLI were not working.
### Manage Organization API tokens with the Astro CLI
You can now manage [Organization API tokens](/docs/astro/organization-api-tokens) using the following CLI commands:
* [`astro organization token create`](/docs/cli/v1.40/astro-organization-token-create)
* [`astro organization token roles`](/docs/cli/v1.40/astro-organization-token-roles)
* [`astro organization token list`](/docs/cli/v1.40/astro-organization-token-list)
* [`astro organization token update`](/docs/cli/v1.40/astro-organization-token-update)
* [`astro organization token rotate`](/docs/cli/v1.40/astro-organization-token-rotate)
* [`astro organization token delete`](/docs/cli/v1.40/astro-organization-token-delete)
### Download resources from the Astronomer Registry to your Astro project
You can now use the following commands to download resources from the Astronomer Registry:
* `astro registry dag add`
* `astro registry provider add`
The 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.
### Additional improvements
* You can now create Deployments on AWS standard clusters.
* If you belong to only one Workspace, the Astro CLI now uses that Workspace by default for all commands.
### Bug fixes
* Fixed an issue where the Astro CLI could not retrieve the health status of a Deployment.
* Fixed an issue where you could not set `worker_concurrency` to 0 in a Deployment file.
### Bug fixes
* Fixed an issue where the `isHighAvailability` and `CICDEnforcement` fields in Deployment files were not processed correctly.
### Manage Teams using the Astro CLI
You can now manage [Astro Teams](/docs/astro/manage-teams) using the following CLI commands:
* [`astro workspace team add`](/docs/cli/v1.40/astro-workspace-team-add)
* [`astro workspace team list`](/docs/cli/v1.40/astro-workspace-team-list)
* [`astro workspace team update`](/docs/cli/v1.40/astro-workspace-team-update)
* [`astro workspace team remove`](/docs/cli/v1.40/astro-workspace-team-remove)
* [`astro organization team create`](/docs/cli/v1.40/astro-organization-team-create)
* [`astro organization team list`](/docs/cli/v1.40/astro-organization-team-list)
* [`astro organization team update`](/docs/cli/v1.40/astro-organization-team-update)
* [`astro organization team delete`](/docs/cli/v1.40/astro-organization-team-delete)
* [`astro organization team user remove`](/docs/cli/v1.40/astro-organization-team-user)
* [`astro organization team user add`](/docs/cli/v1.40/astro-organization-team-user)
* [`astro organization team user list`](/docs/cli/v1.40/astro-organization-team-user)
You can use these commands in automated workflows with [Workspace API tokens](/docs/astro/workspace-api-tokens) and [Organization API tokens](/docs/astro/organization-api-tokens).
### Manage Workspace API tokens with the Astro CLI
You can now manage [Workspace API tokens](/docs/astro/workspace-api-tokens) using the following CLI commands:
* [`astro workspace token create`](/docs/cli/v1.40/astro-workspace-token-create)
* [`astro workspace token add`](/docs/cli/v1.40/astro-workspace-token-add)
* [`astro workspace token list`](/docs/cli/v1.40/astro-workspace-token-list)
* [`astro workspace token update`](/docs/cli/v1.40/astro-workspace-token-update)
* [`astro workspace token rotate`](/docs/cli/v1.40/astro-workspace-token-rotate)
* [`astro workspace token delete`](/docs/cli/v1.40/astro-workspace-token-delete)
These commands can be used to manage API tokens as part of an automated workflow.
### Additional improvements
* You can now specify the `--cluster-type "dedicated"` flag when using `astro deployment create` to create a Deployment on a dedicated cluster in Astro Hosted.
* You can now retrieve a Deployment's Workload Identity when using `astro deployment inspect`.
* You can now specify the `--enforce-cicd` flag with `astro deployment create` and `astro deployment update` to [enforce CI/CD](/docs/astro/deployment-details#enforce-ci/cd-deploys) on a given Deployment.
* You can now [manage Deployments as code](/docs/astro/manage-deployments-as-code) on Astro Hosted.
### Bug fixes
* Fixed an issue where you could not create a Deployment on a standard Hosted cluster.
### New commands to manage Airflow resources on Deployments
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 list`](/docs/cli/v1.40/astro-deployment-connection-list)
* [`astro deployment connection create`](/docs/cli/v1.40/astro-deployment-connection-create)
* [`astro deployment connection update`](/docs/cli/v1.40/astro-deployment-connection-update)
* [`astro deployment connection copy`](/docs/cli/v1.40/astro-deployment-connection-copy)
* [`astro deployment airflow-variable list`](/docs/cli/v1.40/astro-deployment-airflow-variable-list)
* [`astro deployment airflow-variable create`](/docs/cli/v1.40/astro-deployment-airflow-variable-create)
* [`astro deployment airflow-variable update`](/docs/cli/v1.40/astro-deployment-airflow-variable-update)
* [`astro deployment airflow-variable copy`](/docs/cli/v1.40/astro-deployment-airflow-variable-copy)
* [`astro deployment pool list`](/docs/cli/v1.40/astro-deployment-pool-list)
* [`astro deployment pool create`](/docs/cli/v1.40/astro-deployment-pool-create)
* [`astro deployment pool update`](/docs/cli/v1.40/astro-deployment-pool-update)
* [`astro deployment pool copy`](/docs/cli/v1.40/astro-deployment-pool-copy)
### Additional improvements
* You can now use the `--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.
* You can now use Organization API tokens to automate Astro CLI tokens. Specify the Organization API token using the environment variable `ASTRO_API_TOKEN` in the environment where you run the Astro CLI.
* You can now create a custom Docker/Podman compose file for your Astro project with the command `astro dev object export --compose`. After you modify the file, you can use it to start your project with `astro dev start --compose-file `.
* You can now set `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.
* The Astro CLI now automatically trims quotation marks from the beginning and end of environment variables being pushed to Astro.
* The command `astro user invite` has been deprecated.
### Bug fixes
* Fixed an issue were `astro deployment variable create/update` was not producing error when it failed to create an environment variable.
* Fixed an issue were Podman deploys were failing if the user didn't have the Docker CLI installed.
### Bug fixes
* Fixed an issue where `astro workspace user list` didn't work when using a Workspace API token.
### New commands to manage Astro Workspaces
You can now manage Astro Workspaces from the Astro CLI using the following new commands:
* [`astro workspace create`](/docs/cli/v1.40/astro-workspace-create)
* [`astro workspace update`](/docs/cli/v1.40/astro-workspace-update)
* [`astro workspace delete`](/docs/cli/v1.40/astro-workspace-delete)
To automate Workspace management, you can run these commands using a [Workspace API token](/docs/astro/workspace-api-tokens).
### Bug fixes
* Fixed an issue where the CLI added the `dags` folder to `.dockerignore` whenever an image build was interrupted, resulting in dags not being deployed on the next image build.
The command `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`](/docs/cli/v1.40/astro-organization-user-invite) before Astro CLI v1.15.0 is released.
### New flag `--clean-output` for Deployment commands
You 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 inspect`
* `astro deployment create`
* `astro deployment update`
This is helpful for users automating actions with deployment files, like using the Deploy Action template with [Github Actions](/docs/astro/ci-cd-templates/template-overview).
### New environment variable `ASTRO_HOME`
The 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.
### Additional improvements
* The command `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.
### Bug fixes
* Fixed an issue where you couldn't authenticate to the Astro from the Astro CLI using single sign-on (SSO).
### Additional improvements
* You can now expose your local Airflow webserver and postgres database to all networks you're connected to using the following command:
```sh wrap theme={null}
astro config set airflow.expose_port true
```
* 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=` 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`](/docs/cli/v1.40/astro-run) commands and exclude `astro-run-dag` from any images built by the CLI using the following command:
```sh wrap theme={null}
astro config set disable_astro_run true
```
* In new Astro projects, `requirements.txt` now includes a commented list of the pre-installed provider packages on Astro Runtime.
### Bug fixes
* Fixed an issue where the default dag integrity test would sometimes generate an error for valid uses of `os.getenv(key,default)`.
* Fixed bugs in the default Astro project dags.
### Support for Podman
You can now configure the Astro CLI to run Airflow locally and deploy to Astro using [Podman](https://podman.io/). 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](/docs/cli/v1.43/use-podman).
### Bug fixes
* Fixed an issue where you couldn't run Astro CLI commands with a Deployment API key if you logged out of your personal account using `astro logout`.
* Fixed an issue where you couldn't set the minimum worker count for a worker queue to zero.
* Fixed an issue where running `astro deploy` would not return an error when you specified a Deployment name that didn't exist.
* Fixed an issue where you could not update a Deployment with a file using a Deployment API key.
### New commands to manage Astro users
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`](/docs/cli/v1.40/astro-organization-user-invite) and [`astro workspace`](/docs/cli/v1.40/astro-workspace-user-add) command references.
### Manage Astro Deployments as code
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](/docs/cli/v1.40/astro-deployment-create).
### New `--dag-file` flag for `astro run`
By 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.
### Additional improvements
* When you run Airflow locally, you no longer need to enter credentials to log in to the Airflow UI.
* When you run Airflow locally, you can now access to the Airflow UI **Configurations** page (**Admin** > **Configurations**). This page shows the current configuration for your environment, including environment variables and Astro Runtime defaults.
* The Astro CLI now reminds you when a new version of the Astro CLI is available. To turn this feature off, run `astro config set -g upgrade_message false`.
### Additional improvements
* The `__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.
* Clarified the message that appears when you run `astro deployment update --dag-deploy enable` and dag-only deploys were already enabled for the Deployment.
### Bug fixes
* Fixed an issue related to the [SQLAlchemy connection](https://airflow.apache.org/docs/apache-airflow/stable/configurations-ref.html#sql-alchemy-conn) (\[`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.
### Additional improvements
* Improved error handling for `astro login`.
* Added minor performance improvements to `astro run`
### Bug fixes
* Fixed an issue where `astro run` could not locate `airflow_settings.yaml` when running a local Airflow environment.
* Fixed an issue were the Airflow settings file created by `astro dev object export` was not compatible with `astro run`.
### Bug fixes
* Fixed an issue where you could not use `astro deploy` if you did not have an `.env` file in your Astro project.
### New `astro run` command
You 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](/docs/cli/v1.40/test-your-astro-project-locally).
### Additional improvements
* When you run `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](/docs/astro/deploy-dags).
* The `deployment inspect` command now includes a `dag-deploy-enabled` field, and the fields are now ordered in logical groupings instead of by alphabetical order.
### Bug fixes
* Fixed an issue where configurations specified in the `docker-compose.override.yaml` file of an Astro project were not properly applied.
* Fixed an issue where `astro login` didn’t recognize some valid domains.
### Deploy only dags with `astro deploy -—dags`
Use `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:
* Is significantly faster than running `astro deploy` when you only make changes to the `dags` directory.
* Does not cause your workers and schedulers to terminate and restart every time you make a change to a dag and does not result in downtime for your Deployment.
* Enables your team to create separate CI/CD processes for deploying dags and deploying other changes to your Astro project.
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](/docs/astro/deploy-dags). For example CI/CD workflows with this feature enabled, see [CI/CD](/docs/astro/set-up-ci-cd).
### New `astro deployment inspect` command
You 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](/docs/cli/v1.40/astro-deployment-inspect).
### Additional improvements
* The outputs for `astro dev parse` and `astro dev pytest` commands have improved legibility by no longer including Docker container logs.
* The `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.
* You can now provide either an Organization name or ID when running `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.
### Bug fixes
* Fixed an issue where `astro deploy` with `colima` was failing due to an issue with registry authentication
* Fixed an issue where `astro deployment list` didn't display the Workspace ID for a Deployment
### Bug fixes
* Fixed an issue where authenticating to Astronomer Software with `interactive=true` in your CLI configuration resulted in a 502 error.
### New commands to manage Airflow objects
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:
* Update objects in a locally running Airflow environment without restarting it.
* Quickly move Airflow objects from a local testing environment to an Astro Deployment.
### New commands to configure worker queues on Astro
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.
### New commands to manage Organization
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 to
* `astro organization switch` allows you to switch between Organizations
To use these commands, you must be authenticated to your primary Organization through the CLI.
### Additional improvements
* The Astro CLI for Windows is now distributed as an `.exe` file.
* You can now define connections in the `conn_extra` field of `airflow_settings.yaml` as YAML blocks instead of stringified JSON objects.
* You can now use the `--settings-file` flag with `astro dev start` to load and update Airflow objects in your environment from the configuration file of your choosing.
### Bug fixes
* Fixed an issue where the Astro CLI generated incorrect URLs for the Deployment dashboard
* Improved error handling and messaging when the Astro CLI doesn't recognize the image in a project's Dockerfile
### Bug fixes
* Fixes an issue where you could not push a deprecated version of Astro Runtime to a Deployment, even if that Deployment was already running that version. Instead of blocking deploys, the Astro CLI now shows only a warning.
### Additional improvements
* You can now use a new `--deployment-name` flag with all `astro deployment` commands to specify a Deployment by its name instead of its Deployment ID.
* You can now use a new `--wait` flag with `astro deployment create` to have the command wait until the new Deployment is healthy before completing.
* You can now use a new `--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.
* The `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.
### Bug fixes
* Fixed an issue where some environment variable values could be truncated when using `astro deployment variable create --load`.
* Fixed an issue where users with access to more than one Astro Organization could only log in to their primary Organization. Now, users can authenticate to multiple Organizations with a [token login](/docs/cli/v1.43/astro-login). Native support for organization commands is coming soon.
### New command to bash into local Airflow containers
You can now run bash commands in any locally running Airflow container using `astro dev bash`. You can use this to:
* Verify the packages installed in your Airflow environment.
* Run python commands and test python functions in your Airflow environment.
* Explore the local Airflow metadata database with a simple `postgres` command.
For more information, see the [CLI command reference](/docs/cli/v1.40/astro-dev-bash).
### New command to invite a user to an Astro Organization
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](/docs/cli/v1.40/astro-organization-user-invite).
### Additional improvements
* Create multiple environment variables more easily by passing a list of key and value pairs to `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.
* If Docker Desktop isn't already running on your machine, the CLI automatically starts it when you run `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.
* The Airflow UI now automatically opens in your default web browser after you run `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.
### Deploy a custom Docker image with new `--image-name` flag
You can now deploy your Astro project with a custom Docker image by running `astro deploy --image-name `, 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](/docs/cli/v1.40/private-python-packages).
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 start`
* `astro dev restart`
* `astro dev parse`
* `astro dev pytest`
For more information about this command, see the [CLI command reference](/docs/cli/v1.40/astro-deploy).
### New token login method for Astro
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](/docs/cli/v1.40/astro-login).
### Skip parsing dags before deploys
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:
* Add `skip_parse: true` to your `.astro/config.yaml` file.
* Add `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](/docs/cli/v1.40/test-your-astro-project-locally). For more information about deploying to Astro, see [Deploy code](/docs/astro/deploy-code).
### Additional improvements
* Upgraded the CLI to Go version 1.18, which includes improvements to both performance and the development experience. See the [Go Blog](https://go.dev/blog/go1.18).
### Bug fixes
* Fixed an issue where parsing dags during a deploy would kill a local project
* Fixed an issue where `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.
### Bug fixes
* Fixed an issue where `astro deploy` would kill a running project
### Deployment API keys now work with Deployment commands
You can now run the following commands with a Deployment API key:
* `astro deploy`
* `astro deployment list`
* `astro deployment logs`
* `astro deployment update`
* `astro deployment delete`
* `astro deployment variable list`
* `astro deployment variable create`
* `astro deployment variable update`
Previously, you could run only the `astro deploy` command with a Deployment API key. For more information on API keys.
### Easier way to determine Deployment ID on Deployment commands
The Astro CLI now follows a new process to determine which Deployment to run a command against. Specifically:
* The Astro CLI first checks if a Deployment ID is specified as an argument to the command. For example, `astro deployment update `.
* If not found, it checks for a Deployment ID in the `./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.
* If only one Deployment exists in your Workspace, the CLI automatically runs the command for that Deployment without requiring that you specify its Deployment ID.
* If a Deployment API key is set as an OS-level environment variable on your machine or in a CI/CD pipeline, the CLI automatically runs the command for that Deployment without requiring a Deployment ID.
* If multiple Deployments exist in your Workspace and a Deployment API key is not found, the CLI will prompt you to select a Deployment from a list of all Deployments in that Workspace.
* If the Astro CLI doesn't detect a Deployment across your system, it will prompt you to create one.
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](/docs/astro/set-up-ci-cd).
### Bug fixes
* Fixed an issue where only Workspace Admins could create Deployments
### Bug fixes
* Fixed an issue where `astro deploy`, `astro dev parse`, and `astro dev pytest` failed for some users
### A shared CLI for all Astronomer users
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:
```sh wrap theme={null}
# Before upgrade
astrocloud dev init
# After upgrade
astro dev init
```
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`:
```sh wrap theme={null}
# Before upgrade
astrocloud auth login
# After upgrade
astro login
```
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.
**Possible Breaking Change**
If you currently have CI/CD pipelines that install the `astrocloud` executable of the Astro CLI, we encourage you to update them to use the latest version of `astro` to ensure reliability. All `astrocloud` commands will continue to work for some time but will be deprecated by Astronomer soon.
For updated CI/CD examples, see [CI/CD](/docs/astro/set-up-ci-cd).
### New Command To Set Astro Project Configurations
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](/docs/cli/v1.40/astro-config-set).
### New Command To Switch Between Astronomer Contexts
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 ](/docs/cli/v1.40/astro-context-switch).
For more information about these commands, see the [CLI command reference ](/docs/cli/v1.40/astro-context-switch).
### Additional improvements
* Astro CLI documentation has been refactored. You can now find all information about the CLI, including installation steps and the command reference, under the [Astro CLI tab](/docs/cli/v1.40/overview).
* The nonfunctional `--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.
### New command to update Deployment environment variables
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](/docs/cli/v1.40/astro-deployment-variable-create).
### Additional improvements
* When you run `astro workspace switch`, you can now specify a `` as part of the command and avoid the prompt to manually select a Workspace
* You now need to provide an email address only the first time you run `astro 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 again
* The `astro deploy` and `astro dev start` commands will now inform you if there is a new version of Astro Runtime available
### Bug fixes
* Fixed an issue were the `astro deployment variable create —load` command would fail if the specified `.env` file had a comment (e.g. `# `) in it
* Fixed an issue were Deployment API keys would not work locally for some users
### New command to create and update environment variables
`astro deployment variable create` is a new Astro CLI command that allows you to create and update [environment variables](/docs/astro/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](/docs/cli/v1.40/astro-deployment-variable-create).
### New command to list and save Deployment environment variables
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](/docs/cli/v1.40/astro-deployment-variable-list).
### Additional improvements
* You can now specify a custom image name in your Astro project's `Dockerfile` as long as the image is based on an existing Astro Runtime image
### Additional improvements
* Improved the performance of `astro dev start`
* When you successfully push code to a Deployment with `astro deploy`, the CLI now provides URLs for accessing the Deployment's Cloud UI and Airflow UI pages.
### Additional improvements
* The `astro dev start` command should now be \~30 seconds faster
* When `astro dev parse` results in an error, the error messages now specify which dags they apply to
* If your dags don't pass the basic unit test that's included in your Astro project (`test_dag_integrity.py` ), running them with `astro dev pytest` will now provide more information about which part of your code caused an error
### Bug fixes
* Fixed an issue where running `astro dev parse/pytest` would occasionally result in an "orphaned containers" warning
* Fixed an issue where `astro dev parse/pytest` would crash when parsing projects with a large number of dags
* Fixed an issue were some `docker-compose.override.yml` files would cause `astro dev parse/pytest` to stop working
Astro CLI 1.3.2 is a direct patch replacement for 1.3.1, which is no longer available for download because it includes a critical bug related to `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.
### Support for identity-based login flow
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.
### Additional improvements
* `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.
* The `test` directory generated by `astro dev init` now includes more example pytests.
### Bug fixes
* Partially fixed `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`.
* Fixed an issue where running `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.
### New command to parse dags for errors
`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 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](/docs/cli/v1.40/astro-dev-parse). For more guidance on testing dags locally, see [Test dags locally](/docs/cli/v1.40/test-your-astro-project-locally#unit-test-dags).
### `astro deploy` parses dags by default
To 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](/docs/cli/v1.40/astro-deploy).
**Breaking Change**
For Deployments running Astro Runtime 4.1.0+, `astro deploy` will no longer complete the code push to your Deployment if your dags contain basic errors. If any files in your Astro project contain these errors, then certain deploys might stop working after you upgrade the Astro CLI to 1.3.0.
To maintain the CLI's original behavior, use `astro deploy --force`. This command forces a deploy even if errors are detected in your dags.
### New command to update Deployment configurations
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:
* Deployment name
* Deployment description
* Scheduler resources
* Scheduler replicas
* Worker resources
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](/docs/astro/deployment-settings). For more information about this command, see [CLI command reference](/docs/cli/v1.40/astro-deployment-update).
### Deploy to Astro with Deployment API keys for simpler CI/CD
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:
* Installs the Astro CLI.
* Runs `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](/docs/astro/set-up-ci-cd).
### 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](https://docs.pytest.org/en/7.0.x/index.html), 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:
* Python and Airflow syntax errors.
* Import errors.
* Dependency conflicts.
* Unique dag IDs.
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](/docs/cli/v1.40/test-your-astro-project-locally).
### New command to view Deployment scheduler Logs
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](/docs/cli/v1.40/astro-deployment-logs).
### New commands to create and delete Deployments on Astro
You can now use the Astro CLI to create and delete Deployments on Astro with two new commands:
* `astro deployment create`
* `astro deployment delete`
These commands are functionally identical to the [Deployment configuration](/docs/astro/deployment-settings) and deletion process in the Astro UI. For more information, see the [CLI command reference](/docs/cli/v1.40/astro-deployment-create).
### New `astro dev restart` command to test local changes
For 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`.
### Support for the triggerer in local Airflow environments
The Astro CLI now supports the Apache Airflow [triggerer component](https://airflow.apache.org/docs/apache-airflow/stable/authoring-and-scheduling/deferring.html?) in a local environment. This means that you can test dags that use [deferrable operators](/docs/learn/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+.
### Additional improvements
* Postgres has been upgraded from 12.2 to [12.6](https://www.postgresql.org/docs/12/release-12-6.html) for local Airflow environments.
### Introducing the Astro CLI
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:
```sh wrap theme={null}
astro # E.g. `astro dev start`
```
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](/docs/cli/v1.40/install-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.
### New authentication flow
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.
### Improved local development
Astro CLI 1.0.0 includes several improvements to the local development experience:
* You can now run `astrocloud dev start` with [Docker Buildkit](https://docs.docker.com/develop/develop-images/build_enhancements/) enabled. This resolves a [common issue](https://forum.astronomer.io/t/buildkit-not-supported-by-daemon-error-command-docker-build-t-airflow-astro-bcb837-airflow-latest-failed-failed-to-execute-cmd-exit-status-1/857) where users with Docker Buildkit enabled could not run this command.
* After running `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.
### Additional improvements
* `astrocloud deploy` now shows a list of your Deployments in the order by which they were created instead of at random.
### Improved example dags
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.py`
* `example-dag-advanced.py`
The 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.
### Bug fixes
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.
* Bug Fix: Fixed an issue where users saw errors related to S3 in webserver logs when running locally (e.g. `Failed to verify remote log exists s3:///`).
* Improved help text throughout the CLI
* This release contains changes exclusively related to the Astro CLI developer experience.
* Improvement: `./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](/docs/runtime/upgrade-astro-runtime) for existing projects.
* Improvement: Updated error messages throughout the CLI to be more clear and useful
* Improvement: Bumped the default Astro Runtime version for new projects to [`3.0.2`](/docs/runtime/runtime-release-notes#astro-runtime-3-0-2)
* Improvement: You can now use `./astro dev run` to run Airflow CLI commands
* Improvement: You can now use `./astro dev logs` to show logs for the Airflow scheduler and webserver when developing locally
* Improvement: Bumped the default Astro Runtime version for new projects to [`3.0.0`](/docs/runtime/runtime-release-notes#astro-runtime-3-0-1)
* Improvement: Updated help text throughout the CLI
* Improvement: Projects created with `./astro dev init` now include a README file
* Bug Fix: Fixed an issue where users could not push dags to Deployments on Astro via the CLI.
* Improvement: You can now run `./astro login` without specifying a domain (`astronomer.io` is always assumed).