Skip to main content
Version: 0.28

Astronomer CLI Reference Guide

Overview

Astronomer's open source CLI is the easiest way to run Apache Airflow on your local machine. From the CLI, you can create a local Apache Airflow instance with a dedicated Webserver, Scheduler and Postgres Database. If you're an Astronomer customer, you can use the Astronomer CLI to create and manage users, Workspaces, Airflow Deployments, service accounts, and more.

This document contains information about all commands and settings available in the Astronomer CLI, including examples and flags. It does not contain detailed guidelines on each command, but each section provides resources for additional information in a Related documentation section if it's available.

Installation

There are two ways to install any version of the Astronomer CLI:

For a detailed changelog of all Astronomer CLI versions, see GitHub Releases.

Note: Both methods only work for Unix (Linux+Mac) based systems. If you're running on Windows 10, follow this guide to get set up with Docker for WSL.

Prerequisites

The Astronomer CLI installation process requires Docker (v18.09 or higher).

Install with Homebrew

If you have Homebrew installed, run:

brew install astronomer/tap/astro

To install a specific version of the Astronomer CLI, you'll have to specify @major.minor.patch. To install v0.16.1, for example, run:

brew install astronomer/tap/astro@0.16.1

Install with cURL

To install the latest version of the Astronomer CLI, run:

curl -sSL https://install.astronomer.io | sudo bash

To install a specific version of the Astronomer CLI, specify -s -- major.minor.patch as a flag at the end of the cURL command. To install v0.16.1, for example, run:

curl -sSL https://install.astronomer.io | sudo bash -s -- v0.16.1

Note for MacOS Catalina Users:

As of macOS Catalina, Apple replaced bash with ZSH as the default shell. Our CLI install cURL command currently presents an incompatibility error with ZSH, sudo and the pipe syntax.

If you're running macOS Catalina and beyond, do the following:

  1. Run sudo -K to reset/un-authenticate
  2. Run the following to install the CLI properly:
curl -sSL https://install.astronomer.io | sudo bash -s < /dev/null

Confirm the install

To make sure that you have the Astronomer CLI installed on your machine, run:

astro version

If the installation was successful, you should see the version of the CLI that you installed in the output:

Astronomer CLI Version: 0.15.0
Git Commit: c4fdeda96501ac9b1f3526c97a1c5c9b3f890d71

For a breakdown of subcommands and corresponding descriptions, you can always run astro or astro --help.

astro is a command line interface for working with the Astronomer Platform.

Usage:
astro [command]

Available Commands:
auth Manage astronomer identity
cluster Manage Astronomer EE clusters
completion Generate autocompletions script for the specified shell (bash or zsh)
config Manage astro project configurations
deploy Deploy an airflow project
deployment Manage airflow deployments
dev Manage airflow projects
help Help about any command
upgrade Check for newer version of Astronomer CLI
user Manage astronomer user
version Astronomer CLI version
workspace Manage Astronomer workspaces

Flags:
-h, --help help for astro

Use "astro [command] --help" for more information about a command.

Once you've successfully installed the CLI, use the remainder of this guide to learn more about the CLI's available commands.

astro auth

Authenticates you to Astronomer.

Usage

Run astro auth <subcommand> <base-domain> in your terminal to log in or out of your Astronomer platform. This is equivalent to using the login screen of the Software UI.

If you have access to more than one Astronomer platform, each will have a unique <base-domain>. When switching between platforms, make sure to log out of one <base domain> before logging into another.

Subcommands

SubcommandUsage
loginTo log in to Astro, run astro auth login. For Software, run astro auth login <base-domain>.
logoutTo log out of Astro, run astro auth logout. For Software, run astro auth logout <base-domain>.

astro cluster

Allows Astronomer Software users to switch between the Software installations they have access to.

Usage

Run astro cluster <subcommand> in your terminal to see or access available Software installations.

Subcommands

SubcommandUsage
listRun astro cluster list to retrieve a list of all clusters to which you've previously authenticated.
switchRun astro cluster switch to retrieve a list of available clusters, then enter the ID number of the cluster you want to switch to. Once that command is successful, authenticate to that cluster by running astro auth login <base-domain>.

astro completion

Generates autocompletion scripts for Astronomer.

Usage

Use astro completion <subcommand> to generate autocompletion scripts, which can be used to automate workflows on Astronomer that require multiple CLI commands.

Note: If you're running on MacOS, make sure to install Bash Completion before creating autocompletion scripts. To do so via Homebrew, run:

```sh
brew install bash-completion
```

Subcommands

SubcommandUsage
bashRun astro completion bash to show the bash shell script for autocompletion in Astronomer. Use this output to modify or view your autocompletion scripts.
zshRun astro completion zsh to show the zsh shell script for autocompletion in Astronomer. Use this output to modify or view your autocompletion scripts.

astro config

Modifies certain platform-level settings on Astronomer Software without needing to manually adjust them in your config.yaml file.

Usage

Run astro config get <setting-name> to list the value for a particular setting in your config.yaml file. To update or override a value, run astro config set <setting-name> <value>.

The settings that you can update via the command line are:

  • cloud.api.protocol
  • cloud.api.port
  • cloud.api.ws_protocol
  • cloud.api.token
  • context
  • contexts
  • houston.dial_timeout
  • local.houston
  • local.orbit
  • postgres.user
  • postgres.password
  • postgres.host
  • postgres.port
  • project.deployment
  • project.name
  • project.workspace
  • webserver.port
  • show_warnings

Subcommands

SubcommandUsage
getShow current values for the above configuration settings.
setUpdates a setting in your platform to a new value.

astro deploy

Deploys code in your Airflow project directory to any Airflow Deployment on Astronomer.

Usage

Run astro deploy <your-deployment-release-name> [flags] in your terminal to push a local Airflow project as a Docker image to your Airflow Deployment on Astronomer.

If you have the appropriate Workspace and Deployment-level permissions, your code is packaged into a Docker image, pushed to Astronomer's Docker Registry, and applied to your Airflow Webserver, Scheduler(s), and Worker(s).

To identify your Deployment's release name, go to Settings > Basics > Release Name in the Software UI or run astro deployment list.

If you run astro deploy without specifying your-deployment-release-name, the Astronomer CLI will list all Airflow Deployments in your Workspace to choose from.

Flags

FlagValue TypeUsage
--forceNoneForces deploy even if there are uncommitted changes.
--promptNoneForces prompt for choosing a target Deployment.
--saveNoneSaves this directory/Deployment combination for future deploys.
--workspace-idStringLists available Deployments in your Workspace and prompts you to pick one.
--no-cacheNoneDo not use any images from the container engine's cache when building your project.

astro deployment

Manages various Deployment-level actions on Astronomer.

Usage

Run astro deployment <subcommand> in your terminal to create, delete, or manage an Airflow Deployment on Astronomer. See the following entries of this guide for more information on each subcommand.

When managing an existing Deployment using subcommands such as delete and logs, you additionally need to specify a Deployment in your command. In this case, you would run astro deployment <subcommand> --deployment-id=<deployment-id>.

astro deployment airflow upgrade

Initializes the Airflow version upgrade process on any Airflow Deployment on Astronomer.

Usage

Run astro deployment airflow upgrade --deployment-id to initialize the Airflow upgrade process. To finalize the Airflow upgrade process, complete all of the steps as described in Upgrade Apache Airflow on Astronomer.

If you do not specify --desired-airflow-version, this command will output a list of available versions of Airflow you can choose from and prompt you to pick one. The Astronomer CLI will only make available versions of Airflow that are higher than the version you're currently running in your Dockerfile.

Flags

FlagValue TypeUsage
--deployment-idStringThe ID of the Deployment for which you want to upgrade Airflow. To find your Deployment ID, run astro deployment list.
--desired-airflow-versionStringThe Airflow version you're upgrading to (e.g. 1.10.14).

astro deployment create

Creates a new Airflow Deployment in your current Astronomer Workspace.

Usage

Run astro deployment create <new-deployment-name> [flags] to create a new Deployment in your Astronomer Workspace. This is equivalent to using the New Deployment button in the Software UI.

Flags

FlagValue TypeUsage
--airflow-versionStringThe Airflow version for the new Deployment.
--cloud-roleStringAppend an AWS or GCP IAM role to your Airflow Deployment's Webserver, Scheduler, and Worker Pods.
--executorStringThe Executor type for the Deployment. Can be local, celery, or kubernetes. If no executor is specified, then celery is used.
--release-nameStringA custom release name for the Airflow Deployment. Applies only to Deployments on Astronomer Software.
--dag-deployment-typeStringThe DAG deploy method for the Deployment. Can be either image or volume. The default value is image.
--nfs-locationStringThe location for an NFS volume mount, specified as: <IP>:/<path>. Must be specified when --dag-deployment-type=volume. Input is automatically prepended with nfs:/ - do not include this in your input.
--triggerer-replicasIntegerThe number of replica Triggerers to provision for the Deployment.

astro deployment delete

Deletes an Airflow Deployment from an Astronomer Workspace. This is equivalent to the Delete Deployment action in the Software UI.

Usage

astro deployment delete <your-deployment-id>

astro deployment list

Generates a list of Airflow Deployments in your current Astronomer Workspace.

Usage

astro deployment list [flags]

Flags

FlagValue TypeUsage
--allNoneGenerates a list of running Airflow Deployments across all Workspaces that you have access to.

astro deployment logs

Returns logs from your Airflow Deployment's Scheduler, Webserver, Triggerer, and Celery Workers.

Usage

You can run any of the following commands depending on which logs you want to stream:

  • astro deployment logs scheduler [flags]
  • astro deployment logs webserver [flags]
  • astro deployment logs workers [flags]
  • astro deployment logs triggerer [flags]

Flags

FlagValue TypeUsage
--followNoneSubscribes to watch more logs.
--searchStringSearches for the specified string within the logs you're following.
--sinceLookback time in h or m (e.g. 5m, 2h)Limits past logs to those generated in the lookback window.

astro deployment service-account create

Creates a Deployment-level service account on Astronomer, which you can use to configure a CI/CD pipeline or otherwise interact with the Astronomer Houston API.

Usage

astro deployment service-account create --deployment-id=<your-deployment-id> --label=<your-service-account-label> [flags]

Flags

FlagValue TypeUsage
--categoryStringThe category for the new service account as displayed in the Software UI. This is optional, and the default value is Not set.
--deployment-id (Required)StringThe Deployment you're creating a service account for.
--label (Required)StringThe name or label for the new service account.
--roleStringThe User Role for the new service account. Can be viewer, editor, or admin. The default value is viewer.
--system-saBooleanWhether this service account is a System service account. Default value is false.
--user-idStringThe ID for the new service account.

astro deployment service-account delete

Deletes a service account for a given Deployment.

Usage

astro deployment service-account delete <your-service-account-id> [flags]

Flags

FlagValue TypeUsage
--deployment-id(Required)StringThe Airflow Deployment in which the service account is configured. Use this flag as an alternative to specifying <your-service-account-id>. To get this value, run astro deployment list.

astro deployment service-account get

Shows the name, ID, and API key for each service account on a given Deployment.

Usage

Run astro deployment service-account get <service-account-id> --deployment-id=<your-deployment-id> to get information on a single deployment-level service account. To see a list of all service accounts on a Deployment, run astro deployment service-account get --deployment-id=<your-deployment-id>.

Flags

FlagValue TypeUsage
--deployment-id (Required)String--deployment-id (Required)

astro deployment update

Updates various parts of an Airflow Deployment on Astronomer, including metadata, deployment methods, and Executor type. Can also be used to append IAM roles to the Webserver, Scheduler, and Worker pods for Deployments running on Amazon EKS or Google GCP.

Usage

Run astro deployment update <your-deployment-id> [flags] to update a Deployment. The Deployment ID can be found by running astro deployment list.

Note: Only the --cloud-role flag is specified with a --. Additional flags should be written without a leading --.

Flags

FlagValue TypeUsage
--cloud-roleStringThe ARN for the IAM role.
--dag-deployment-typeStringThe DAG deploy method for the Deployment. Can be either image or volume. The default value is image.
--nfs-locationStringThe location for an NFS volume mount, specified as: <IP>:/<path>. Must be specified when --dag-deployment-type=volume. Input is automatically prepended with nfs:/ - do not include this in your input.
labelStringThe label for the Deployment.
descriptionStringThe description for a Deployment.
versionStringThe Airflow version for the Deployment (e.g. v2.0.0).
releaseNameStringThe release name for the Deployment (e.g. planetary-fusion-1382).
alert_emailsStringAn email address which receives Airflow alerts from the Deployment.
typeStringThe type of Deployment. Can be either airflow or flower.
executorStringThe Executor type for the Deployment. Can be either local, kubernetes, or celery.

astro deployment user add

Gives an existing user in a Workspace access to an Airflow Deployment within that Workspace. You must be a Deployment Admin for the given Deployment to complete this action.

Usage

astro deployment user add <user-email-address> --deployment-id=<user-deployment-id> --role<user-role>

Flags

FlagValue TypeUsage
--deployment-id (Required)StringThe ID of the Deployment that the user will be added to. To find this value, run astro deployment list.
--role (Required)StringThe role assigned to the user. Can be DEPLOYMENT_VIEWER, DEPLOYMENT_EDITOR, or DEPLOYMENT_ADMIN. The default value is DEPLOYMENT_VIEWER.

astro deployment user delete

Removes access to an Airflow Deployment for an existing Workspace user. To grant that same user a different set of permissions instead, modify their existing Deployment-level role by running astro deployment user update. You must be a Deployment Admin to perform this action.

Usage

astro deployment user delete --deployment-id=<deployment-id> <user-email-address>

Flags

FlagValue TypeUsage
--deployment-id (Required)StringThe Deployment that the user will be removed from.

astro deployment user list

Outputs a list of all Workspace users who have access to a given Deployment. Use the optional flags to list specific users based on their name, email, or ID.

Usage

astro deployment user list --deployment-id=<deployment-id> [flags]

Flags

FlagValue TypeUsage
--deployment-id (Required)StringThe Deployment that you're searching in.
--emailStringThe email for the user you're searching for.
--nameStringThe name of the user to search for.
--user-idStringThe ID of the user to search for.

astro deployment user update

Updates a user's role in a given Deployment.

Usage

astro deployment user update --deployment-id=<deployment-id> [flags]

Flags

FlagValue TypeUsage
--deployment-id (Required)StringThe Deployment that you're searching in.
--roleStringThe role you're updating the user to. Possible values are DEPLOYMENT_VIEWER, DEPLOYMENT_EDITOR, or DEPLOYMENT_ADMIN. If --role is not specified, DEPLOYMENT_VIEWER is the default value.

astro dev

This set of commands allow you to create and manage a local Airflow environment on your machine. Access to the Astronomer platform is not required.

Usage

astro dev <subcommand> [flags]

Refer to the following sections for information on each subcommand.

astro dev init

Initializes a new Airflow project in your working directory. The set of files generated by this command are required to run Airflow locally and can be deployed to an Airflow Deployment on Astronomer.

Usage

astro dev init [flags]

When you run this command, the following skeleton files are generated in your current directory:

.
├── dags # Where your DAGs go
│ └── example-dag.py # An example DAG that comes with the initialized project
├── Dockerfile # For Astronomer's Docker image and runtime overrides
├── include # For any other files you'd like to include
├── plugins # For any custom or community Airflow plugins
├── airflow_settings.yaml # For your Airflow Connections, Variables and Pools (local only)
├── packages.txt # For OS-level packages
└── requirements.txt # For any Python packages

Flags

FlagValue TypeUsage
--airflow-versionStringThe version of Airflow you want to use. The default value is the latest Airflow version available.
--nameStringThe name for the Airflow project.

astro dev kill

Forces running containers in your local Airflow environment to stop. Unlike astro dev stop, which only pauses running containers, astro dev kill will delete all data associated with your local Postgres metadata database, including Airflow Connections, logs, and task history.

This command is most often used to restart a cluster when testing new DAGs or settings in a non-production environment. After using astro dev kill, you can restart your environment with astro dev start.

Usage

In your project directory, run astro dev kill to delete all data associated with your Airflow Deployment's Postgres metadata database.

astro dev logs

Shows logs for the Scheduler or Webserver in your local Airflow environment.

Usage

Run astro dev logs [flags] to start tracking logs for your Scheduler, Webserver, or Triggerer in your CLI terminal window.

Flags

FlagValue TypeUsage
--followNoneContinues to show the latest outputs from the log.
--schedulerNoneOutputs only Scheduler logs.
--webserverNoneOutputs only Webserver logs.
--triggererNoneOutputs only Triggerer logs.

astro dev ps

Lists all running Docker containers for your local Airflow environment. This command can only be used in a project directory and works similarly to docker ps.

Usage

astro dev ps

astro dev run

Runs a single Airflow CLI command on your local Airflow environment. This command only applies to local development and is not supported for Airflow Deployments on Astronomer.

Usage

astro dev run

astro dev start

Initializes a local Airflow environment on your machine by creating a Docker container for each of Airflow's core components:

  • Postgres
  • Scheduler
  • Webserver
  • Triggerer
info

Logs for the Airflow Triggerer will only show for local environments using Deferrable Operators and running Astronomer Certified 2.0+.

Usage

astro dev start [flags]

Flags

FlagValue TypeUsage
--envStringSpecifies the filepath containing environment variables for the Airflow cluster.
--no-cacheNoneDo not use any images from the container engine's cache when building your project.

astro dev stop

Stops all 3 running Docker containers on your local Airflow environment. Running this command followed by astro dev start is required to push certain types of changes to your Airflow project. Unlike astro dev kill, this command does not prune mounted volumes and will preserve data associated with your local Postgres Metadata Database.

Usage

astro dev stop

astro dev upgrade-check

Runs a script that checks whether all files in your local Airflow project are compatible with Airflow 2.0 by reviewing your DAG code, deployment-level configurations, and Environment Variables, as well as metadata from the Airflow Database. You must be on Airflow 1.10.14+ and in your Airflow project directory to run this command.

Usage

astro dev upgrade-check

astro upgrade

Checks for the latest version of the Astronomer CLI, but does not perform the upgrade.

Usage

astro upgrade

Note: This command only checks whether or not a new version of the Astronomer CLI is available. To actually upgrade the CLI to the latest version, run:

brew install astronomer/tap/astro

astro user create

Creates a new user on Astronomer. An invitation email will be sent to the email address you specify. Once this user creates an account on Astronomer, they are able to join an existing Workspace or create a new Workspace.

Usage

astro user create [flags]

flags

FlagValue TypeUsage
--emailStringSpecifies the email address for the new user. If not specified, you'll be prompted to enter an address during runtime.
--passwordStringSpecifies a password for the new user to access Astronomer with. If not specified, you'll be prompted to enter a password during runtime.

astro version

Displays the running versions of both the Astronomer CLI and the Astronomer platform to which you are authenticated. If the minor versions of the Astronomer CLI and your Astronomer platform don't match, we encourage you to upgrade.

Usage

Run astro version to see both your CLI version and Astronomer platform version.

astro workspace

Manages various Workspace-level actions on Astronomer.

Usage

astro workspace <subcommand> [flags]

For more information on each subcommand, refer to the following sections.

astro workspace create

Creates a new Workspace.

Usage

astro workspace create <new-workspace-name> [flags]

Flags

FlagValue TypeUsage
--descStringThe description for the new Workspace.

astro workspace delete

Deletes a Workspace.

Usage

Run astro workspace delete <your-workspace-id> to delete a Workspace. Your Workspace ID can be found by running astro workspace list. You must have Workspace Admin permissions to a Workspace in order to delete it.

astro workspace list

Generates a list of all Workspaces that you have access to.

Usage

Run astro workspace list to see the name and Workspace ID for each Workspace to which you have access.

astro workspace service-account create

Creates a service account for a given Workspace.

Usage

astro workspace service-account create --workspace-id=<your-workspace> --label=<your-label> [flags]

Flags

FlagValue TypeUsage
--workspace-id (Required)StringThe Workspace you're creating a service account for.
--label (Required)StringA label for the service account.
--categoryStringThe Category for the service account. The default value is Not set.
roleStringThe User Role for the service account. Can be viewer, editor, or admin. The default value is viewer.
--system-saBooleanWhether this service account is a System service account. Default value is false.
--user-idStringThe ID for the new service account.

astro workspace service-account delete

Deletes a service account for a given Workspace.

Usage

astro workspace service-account delete <your-service-account-id> [flags]

Flags

FlagValue TypeUsage
--workspace-idStringThe Workspace in which you want to delete a service account. If this flag is used instead of specifying <your-service-account-id>, you'll be prompted to select a service account from a list of all service accounts on the Workspace.

astro workspace service-account get

Shows the name, ID, and API key for each service account on a given Workspace.

Usage

Run astro deployment service-account get <service-account-id> --workspace-id=<your-workspace-id> to get information on a single service account within a Workspace. To see a list of all service accounts on a Workspace, run astro deployment service-account get --workspace-id=<your-workspace-id>.

Flags

FlagValue TypeUsage
--workspace-idStringThe Workspace you're getting the service account from. Use this flag as an alternative to specifying <your-service-account-id>.

astro workspace switch

Switches the Workspace in which you're working.

Usage

astro workspace switch <workspace-id>

astro workspace update

Updates some of the basic information for your current Workspace.

Usage

astro workspace update [flags]

At least one flag must be specified.

Note: Unlike other commands, do not specify flags for this command with a leading --.

Flags

FlagValue TypeUsage
idStringThe ID for the Workspace.
descriptionStringA description for the Workspace.
labelStringA label for the Workspace

astro workspace user add

Creates a new user in your current Workspace. If the user has already authenticated to Astronomer, they will automatically be granted access to the Workspace. If the user does not have an account on Astronomer, they will receive an invitation to the platform via email.

Usage

astro workspace user add [flags] <user-email-address>

Flags

FlagValue TypeUsage
--workspace-idStringThe Workspace that the user will be added to. Specify this flag if you want to create a user in a Workspace other than your current Workspace.
--roleStringThe role assigned to the user. Can be WORKSPACE_VIEWER, WORKSPACE_EDITOR, or WORKSPACE_ADMIN. If --role is not specified, the default role is WORKSPACE_VIEWER.

astro workspace user remove

Removes an existing user from your current Workspace.

Usage

astro workspace user remove <user-email-address>

astro workspace user list

Outputs a list of all users with access to your current Workspace.

Usage

astro workspace user list [flags]

Flags

FlagValue TypeUsage
--workspace-idStringThe Workspace that you're searching in. Specify this flag if you want to search for users in a Workspace other than your current Workspace.
--emailStringThe email for the user you're searching for.
--nameStringThe name of the user to search for.
--user-idStringThe ID of the user to search for.

astro workspace user update

Updates a user's role in your current Workspace.

Usage

astro workspace user update <user-id> [flags]

Flags

FlagValue TypeUsage
--roleStringThe role you're updating the user to. Possible values are WORKSPACE_VIEWER, WORKSPACE_EDITOR, or WORKSPACE_ADMIN. If --role is not specified, the user is updated to WORKSPACE_VIEWER by default.