Skip to main content
Subscribe to Astro CLI release notes to receive updates via RSS, email, or Slack.
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.
​
September 29, 2026

​
Manage multiple Dag bundles and non-Dag bundles on a Deployment

This feature is in Public Preview.
Astro Deployments now support multiple named Dag bundles and non-Dag bundles, each deployed and versioned independently. Use astro deploy --dag-bundle-name to deploy to a named Dag bundle instead of the default main bundle, or --non-dags to deploy a non-Dag bundle, such as a dbt project, from a separate directory. Manage the bundles registered on a Deployment with the new astro deployment bundle create, list, update, and delete commands.

​
Local Airflow environments now default to Postgres 15

New local Astro projects run Postgres 15 instead of 12.6. An existing project keeps the Postgres major version its local data volume was created with; run astro dev kill followed by astro dev start to move an existing project to the new default. See Configure the Astro CLI.

​
CLI telemetry events are now linked to your Astro Organization

While you’re logged in, astro telemetry events are now linked to your Astro Organization, and the CLI also tracks commands or flags you type that it doesn’t have. Logged-out usage stays anonymous.
​
August 13, 2026

​
Slim, field-filtered dbt manifest at deploy time

When the Cosmos Boost pre-deploy step is enabled, astro deploy and astro dbt deploy now also write a slim, field-filtered .astro/manifest.slim.json next to each dbt manifest. Cosmos Boost can load this smaller file instead of the full manifest.json to reduce Dag-parse time and memory on large dbt projects. This is on by default whenever cosmos_boost.pre_deploy is enabled. To opt out, set ASTRO_COSMOS_BOOST_SLIM_MANIFEST_ENABLED=false.astro dbt cleanup now removes both .astro/dbt_metadata.json and .astro/manifest.slim.json.

​
--dags-path is no longer a hidden flag on astro deploy

The --dags-path flag, which deploys Dags from a path other than your project’s dags directory, is now documented. Combining --dags with --dags-path no longer requires running the command from an Astro project directory.

​
Bug fixes

  • astro deploy now correctly parses Remote Execution Agent client image tags that include a distro segment (for example, -ubi9-) instead of failing with a parse error. When multiple distro variants are available, the CLI prefers the Debian-based image by default.
​
August 6, 2026

​
New astro dbt cleanup command and Cosmos Boost pre-deploy step

Set cosmos_boost.pre_deploy to true to enable an opt-in Cosmos Boost pre-deploy step:
When enabled, astro deploy and astro dbt deploy generate a .astro/dbt_metadata.json file next to each dbt project and dbt manifest in your deploy payload before it leaves your machine. Cosmos Boost uses this file as a cache key instead of hashing your project tree at every Dag parse. This step is disabled by default and has no effect on your deploy while disabled. It doesn’t apply to deploys that use --image-name with a prebuilt image.Use the new astro dbt cleanup command to remove Cosmos Boost artifacts from one or more paths.

​
Adopt operator-managed Deployments on Astro Private Cloud

Public PreviewThis feature is in Public Preview for Astro Private Cloud.
Use the new astro deployment adopt command to bring an Airflow custom resource that the standalone operator created into Astro Private Cloud management. The command creates the matching Deployment record in Astro Private Cloud. It also updates the custom resource. It reconfigures the ingress and the authentication for the Airflow UI. The Deployment’s namespace and its metadata database don’t change.
Use --use-apc-logging to route the adopted Deployment’s logs through Astro Private Cloud logging. This flag updates the logging configuration in the custom resource. Use --use-apc-registry to use the Astro Private Cloud in-cluster registry. If you use --use-apc-registry, you must pre-sync the Deployment’s images.Use the new astro deployment unadopt command to release an adopted Deployment back to operator-only management. The command removes the Deployment record from Astro Private Cloud. It doesn’t delete the Airflow custom resource, its namespace, or its metadata database.Both commands require Astro Private Cloud 2.1.0 or later.

​
Additional improvements

  • astro api describe now expands nested $ref schemas fully instead of stopping at the first reference. Both describe and ls support a new --json flag for machine-readable output.
  • Added a repeatable --build-secret flag to astro dev build, astro dev start, astro dev restart, astro dev parse, astro dev pytest, astro dev upgrade-test, and astro deploy to pass multiple Docker build secrets. The existing --build-secrets flag is deprecated because passing more than one secret to it silently mounted only the last one.
  • Added a dev.build_secrets configuration key so you can set a build secret once instead of passing --build-secret on every astro dev command. Set it with astro config set dev.build_secrets "<secret>" or astro config set --global dev.build_secrets "<secret>".
  • astro deploy to Astro Private Cloud Hybrid Deployments now injects an Airflow 3-compatible monitoring Dag. Previously, only Airflow 2 monitoring Dags were supported.
  • New projects created with astro dev init now add .astro/worktrees/ to .gitignore.
  • Added a --mode flag to astro deployment create for Astro Private Cloud to create Operator-mode Deployments. This flag requires Astro Private Cloud 2.1.0 or later.
  • Deprecated the -h, --hard flag on astro deployment delete for Astro Private Cloud. Astro Private Cloud now hard-deletes Deployments by default, so the flag has no effect. Astronomer plans to remove the flag in a future release.

​
Bug fixes

  • Fixed a bug where a successful interactive re-login after a failed token refresh was immediately overwritten, which left you signed out even though sign-in succeeded.
  • Fixed astro dev pytest and astro dev parse to read container exit codes as integers instead of comparing them as substrings. Previously, exit code 10 was reported as a pass and exit code 130 was reported as a test failure.
  • Fixed astro deploy to return an error instead of exiting successfully when it fails to save the Deployment ID to your project configuration.
  • Fixed astro deployment update on Astro Private Cloud to return an error instead of exiting successfully when you specify an invalid --executor value.
  • Fixed an issue where the Astro CLI created scaffolded projects, templates, and other files and folders with world-writable permissions. Directories now default to 0o755, files to 0o644, and files that can contain credentials to 0o600.
  • Fixed astro api airflow with --paginate and --slurp to page through the full result set for Airflow REST endpoints, such as get_dags. Previously, results were capped at the first page.
  • Fixed commands that accept --workspace-id to honor the flag before requiring a current Workspace context. This fixes non-interactive authentication with an Organization-scoped API token.
  • Fixed astro organization audit-logs export to write a valid gzip file. A regression in 1.43.0 caused the command to write uncompressed data to a file with a .gz extension.
  • Fixed astro organization switch and astro workspace switch to find a target Organization, Workspace, or Deployment that isn’t on the first page of results.
​
July 2, 2026

​
Bug fixes

  • Fixed astro deployment update with --deployment-file against Kubernetes-executor Deployments. A regression in 1.43.0 caused the command to send an empty worker_queues field, which returned an Invalid field values error.
  • Fixed astro deployment airflow-variable copy, astro deployment connection copy, and astro deployment pool copy to retry write requests after a transient server error and to update existing values instead of failing when you rerun a copy after a partial failure.
  • Fixed astro dev start --standalone to show sign-in instructions for Airflow 2 projects after startup. On Linux, Apache Airflow writes a random password for the default admin user to a file, and the CLI didn’t previously tell you where to find it.
​
June 23, 2026
Known issue (resolved in 1.43.1)Astro CLI 1.43.0 fails to run astro deployment update with --deployment-file against Kubernetes-executor Deployments. The command sends an empty worker_queues field, which returns an Invalid field values error.Impact: You cannot update a Kubernetes-executor Deployment using a Deployment file on Astro CLI 1.43.0.Solution: Upgrade to Astro CLI 1.43.1 or later. This issue is fixed in Astro CLI version 1.43.1.

​
New astro env command tree

A new astro env command tree manages Astro Environment Manager objects from your terminal, including environment variables, Airflow connections, Airflow variables, and metrics exports. You can scope each object to a Workspace or a Deployment, link Workspace-scoped objects to specific Deployments, and bulk-import variables from a dotenv file.These commands are distinct from astro deployment variable and astro deployment connection, which write directly to a single Deployment. To manage the same objects in the Astro UI, see Create environment variables in the Astro UI and Create Airflow connections in the Astro UI.

​
Dag processor and component filters for astro deployment logs

astro deployment logs now accepts a --dag-processor flag to show Dag processor logs. A new --component flag shows logs from one or more components by name. The --component flag is repeatable and accepts a comma-separated list, so you can opt into new log sources without a CLI release.

​
Additional improvements

​
Bug fixes

  • Fixed astro deploy to preserve symlinks and honor .dockerignore in the image build context.
  • Fixed astro deploy to preserve the trailing newline in your .dockerignore after building the image.
  • Fixed astro deploy to skip the Dag-only deploy check on Remote Execution Deployments, which previously blocked custom image deploys to those Deployments.
  • Fixed astro dev start standalone mode to set PYTHONPATH to match the Astro Runtime image.
  • Fixed astro dev start --standalone for Airflow 2 projects whose Dockerfile uses a -slim Astro Runtime image. The CLI now strips the -slim suffix when fetching constraints, so the command no longer fails with an HTTP 404 error.
  • Fixed astro dev start in Docker Compose mode so that bare host-environment passthrough resolves. Previously, an environment: [VAR] entry without a value in a docker-compose.override.yml file was ignored.
  • Fixed astro dev init to add .astro/*.local.yml and .astro/*.local.yaml to .gitignore, so local config files are no longer committed unintentionally.
  • Fixed local Astro project setup with the Podman container engine on Windows.
  • Fixed local project discovery on Windows. The CLI now writes routes.json even when the proxy daemon is unavailable, so you can reach local projects by hostname.
​
May 20, 2026

​
Bug fixes

  • Fixed 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.
  • Fixed 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.
​
April 30, 2026
Known issue (resolved in 1.42.1)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.

​
New astro otto command

A 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.

​
Airflow 2 support in standalone mode

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 commands

Most 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:For example:
--json and --output are mutually exclusive.

​
Faster local environment startup

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.

​
Astro Private Cloud 2.0 support

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.

​
Additional improvements

  • 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.
  • The --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.
  • The Astro CLI now reports the local development mode (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.

​
Bug fixes

  • Fixed 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.
  • Fixed 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.
​
April 20, 2026

​
New astro auth command

A 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.

​
New astro api registry command

A 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.

​
Additional improvements

  • Added the -f (--force) flag to astro dev init to initialize a project without confirmation, even in a non-empty directory.
  • Added the -f (--force) flag to astro deployment create to create a Deployment without prompting for confirmation.
  • Added the -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.
  • The -f (--force) flag on astro deploy now also skips the “No Dags found” warning in addition to parse errors and uncommitted changes.
  • Added Swagger 2.0 support and custom spec URL for astro api cloud.
  • Fixed astro dev run to propagate non-zero exit codes from the executed command.
  • Fixed astro dev restart with --allow-existing to preserve the virtual environment in standalone mode.
  • Fixed astro dev start in standalone mode to add include/ to PYTHONPATH.
  • Standardized error messages for missing required flags across commands.
  • Fixed the default image ordering for astro-agent in Airflow version resolution.
  • Improved help text with examples and descriptions across commands.
​
March 12, 2026

​
Bug fixes

  • Fixed the astro dev pytest command to use docker cp instead of bind-mounts for copying test files into the container.
​
March 10, 2026

​
New astro dev build command

A 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.

​
New astro api command

A 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.

​
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:
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.

​
Built-in reverse proxy for multi-instance local development

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.

​
New astro telemetry command

A 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.

​
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. 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 to automatically fix linting issues identified by the upgrade test using ruff.
  • Added the --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.
  • Added --api-server and --dag-processor component filter flags to 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.
​
February 17, 2026

​
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 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.
​
November 4, 2025

​
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.
​
October 27, 2025
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. 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 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.