Skip to main content

Configure the Astro CLI

Every Astro project includes a file called .astro/config.yaml that supports various project-level settings, including:

  • The name of your Astro project.
  • The port for the Airflow webserver and Postgres metadata database.
  • The username and password for accessing the Postgres metadata database.

In most cases, you only need to modify these settings in the case of debugging and troubleshooting the behavior of Airflow components in your local environment.

Set a configuration

You can set Astro configurations at two different scopes: global and project.

For project-specific configurations, Astro stores the settings in a file named .astro/config.yaml in your project directory. This file is generated when you run astro dev init in your project folder. Global configurations, however, are stored in a central location with the Astro executable. If a configuration is set in a project configuration file, it always overrides any of the same configuration in the global configuration file.

Set project configurations

Run the following command in an Astro project to set a configuration for that project:

astro config set <configuration-option> <value>

This command applies your configuration to .astro/config.yaml in your current Astro project. Configurations do not persist between Astro projects.

For example, to update the port of your local Airflow webserver to 8081 from the default of 8080, run:

astro config set webserver.port 8081

Set global configurations

Use the --global flag with astro config set [option] --global to set a configuration for all current and new Astro projects on your machine. Your global Astro CLI configuration is saved in a central location on your machine. For example, the configurations are stored in ~/.astro/config.yaml on Mac OS and /home//.astro/config.yaml on Linux.

Note that you can override global configurations by setting a project-level configuration. If an Astro project contains an .astro/config.yaml file, any configuration values in that file take precedence over the same global configuration values.

The following example shows how to set the local Airflow webserver port to 8081 for all Astro projects on your local machine:

astro config set -g webserver.port 8081

Available CLI configurations


The Astronomer product you're using determines the format and behavior of the configuration commands. Select one of the following tabs to change product contexts.

OptionDescriptionDefault valueValid values
airflow.expose_portDetermines whether to expose the webserver and postgres database of a local Airflow environment to all connected networks.falsetrue, false
cloud.api.protocolThe type of protocol to use when calling the Airflow API in a local Airflow environment.httpshttp, https
cloud.api.portThe port to use when calling the Airflow API in a local environment.443Any available port
cloud.api.ws_protocolThe type of WebSocket (ws) protocol to use when calling the Airflow API in a local Airflow environment.wssws, wss
container.binaryThe name of the container engine.dockerdocker or podman
contextThe context for your Astro project.Empty stringAny available context
disable_astro_runDetermines whether to disable astro run commands and exclude astro-run-dag from any images built by the CLI.falsetrue, false
disable_env_objectsDetermines whether the Astro CLI pulls connections set in the Astro UI to your local environment. When set to true, connections are not pulled to the local environment. Set to false to import connections from the Astro UI for local development. Can be set globally with the -g flag.truetrue, false
duplicate_volumesDetermines if the Astro CLI creates duplicate volumes when running Airflow locally.truetrue or false
local.registryThe location of your local Docker container running Airflow.localhost:5555Any available port
postgres.userThe username for the Postgres metadata database.postgresAny string
postgres.passwordThe password for the Postgres metadata database.postgresAny string
postgres.hostThe hostname for the Postgres metadata database.postgresAny string
postgres.portThe port for the Postgres metadata database.5432Any available port
postgres.repositoryImage repository to pull the Postgres image Postgres image in a repository
postgres.tagThe tag for your Postgres image12.6Any valid image tag
project.nameThe name of your Astro project.Empty stringAny string
show_warningsDetermines whether warning messages appear when starting a local Airflow environment. For example, when set to true, you'll receive warnings when a new version of Astro Runtime is available and when your Astro project doesn't have any DAGs.truetrue, false
skip_parseDetermines whether the CLI parses DAGs before pushing code to a Deployment.falsetrue, false
upgrade_messageDetermines whether a message indicating the availability of a new Astro CLI version displays in the Astro CLI.truetrue, false
webserver.portThe port for the webserver in your local Airflow environment.8080Any available port

Was this page helpful?

Sign up for Developer Updates

Get a summary of new Astro features once a month.

You can unsubscribe at any time.
By proceeding you agree to our Privacy Policy, our Website Terms and to receive emails from Astronomer.