gem-hunter
Language: Go
CLI that makes it easy to create, test and deploy Airflow DAGs to Astronomer
The Astro CLI is a command-line interface for data orchestration. It allows you to get started with Apache Airflow quickly and it can be used with all Astronomer products.
astro [command]
login Log in to the Astro CLIlogout Log out of the Astro CLIdev init Initialize an Astro project in an empty local directorydev start Build your Astro project into a Docker image and spin up a local Docker container for each Airflow componentdev stop Pause all Docker containers running your local Airflow environmentdev restart Stop your Airflow environment, rebuild your Astro project into a Docker image, and restart your Airflow environment with the new Docker imagedeploy Deploy code to a Deployment on Astrodeployment Manage your Deployments running on Astronomerdev Run your Astro project locallyapi Make authenticated requests to Airflow and Astro Cloud REST APIshelp Help about any Astro CLI commandversion Show the running version of the Astro CLIworkspace Manage Astronomer WorkspacesFor a list of available Astro CLI commands, see the Astro CLI command reference.
Use these instructions to install, upgrade, or uninstall the Astro CLI.
To install the Astro CLI on Mac, you'll need:
To install the Astro CLI on Windows, you'll need:
To install the Astro CLI on Windows with the Windows Package Manager winget command-line tool, you'll need:
To install the Astro CLI on Linux, you'll need:
brew install astro
Go to the Releases page of the Astro CLI GitHub repository, scroll to a CLI version, and then download the .exe file that matches the CPU architecture of your machine.
For example, to install v1.0.0 of the Astro CLI on a Windows machine with an AMD 64 architecture, download astro_1.0.0-converged_windows_amd64.exe.
Rename the file astro.exe.
Add the filepath for the directory containing the new astro.exe as a PATH environment variable. For example, if astro.exe is stored in C:\Users\username\astro.exe, you add C:\Users\username as your PATH environment variable. To learn more about configuring the PATH environment variable, see How do I set or change the PATH system variable?.
Restart your machine.
Starting with Astro CLI version 1.6, you can use the Windows Package Manager winget command-line tool to install the Astro CLI.
Open Windows PowerShell as an administrator and then run the following command:
winget install -e --id Astronomer.Astro
curl -sSL install.astronomer.io | bash -sThis installs astro into ~/.local/bin (or $XDG_BIN_HOME if you set it) and needs no root. If that directory is not on your PATH, the installer prints the line to add to your shell profile.
To install system-wide into /usr/local/bin instead, run the installer with sudo:
curl -sSL install.astronomer.io | sudo bash -sTo pick another directory, set ASTRO_INSTALL_DIR. With sudo, set it after sudo, because sudo drops your environment:
curl -sSL install.astronomer.io | ASTRO_INSTALL_DIR="$HOME/bin" bash -s curl -sSL install.astronomer.io | sudo ASTRO_INSTALL_DIR=/opt/bin bash -s
To install a specific version of the Astro CLI, specify the version you want to install at the end of the command:
brew install astro@<major.minor.patch-version>
Delete the existing astro.exe file on your machine.
Go to the Releases page of the Astro CLI GitHub repository, scroll to a CLI version, and then download the .exe file that matches the CPU architecture of your machine.
For example, to install v1.0.0 of the Astro CLI on a Windows machine with an AMD 64 architecture, download astro_1.0.0-converged_windows_amd64.exe.
Rename the file astro.exe.
Add the filepath for the directory containing the new astro.exe as a PATH environment variable. For example, if astro.exe is stored in C:\Users\username\astro.exe, you add C:\Users\username as your PATH environment variable. To learn more about configuring the PATH environment variable, see How do I set or change the PATH system variable?.
Restart your machine.
Starting with Astro CLI version 1.6, you can use the Windows Package Manager winget command-line tool to install a specific version of the Astro CLI.
To install a specific version of the Astro CLI, specify the version you want to install at the end of the command. For example, running the following command in Windows PowerShell as an administrator installs Astro CLI version 1.6:
winget install -e --id Astronomer.Astro -v 1.6.0
To install a specific version of the CLI, specify the version number as a flag at the end of the command. For example, to install v1.1.0 of the CLI, you would run:
curl -sSL install.astronomer.io | bash -s -- v1.1.0As with the latest version, this installs into ~/.local/bin. Use | sudo bash -s -- v1.1.0 for a system-wide install into /usr/local/bin, or set ASTRO_INSTALL_DIR to choose the directory.
The version can take any of these forms, with or without the leading v:
v1.46.1 (or 1.46.1) installs exactly that release. A pre-release such as v1.47.0-rc.1 works the same way.v1.46 (or 1.46) installs the highest 1.46.x release.v1 (or 1) installs the highest 1.x release.A partial version takes the highest stable release, or the highest pre-release while there is no stable one. Among pre-releases the highest by semver wins, so a release candidate outranks nightlies; pass an exact tag to install a specific nightly. A release counts once its checksums are uploaded, and a release marked as a pre-release on GitHub counts as a pre-release even if its tag has no suffix. The installer checks at most the 5 highest tags in each tier, stable first and then pre-release. When it finds nothing to install, it stops and names the tags it tried. A stable tag that is still uploading never lets it fall back to a pre-release. For example, to install the newest 1.46 patch release:
curl -sSL install.astronomer.io | bash -s -- v1.46Every release also publishes an install.sh asset. That copy installs the release it ships with and no other, so the URL itself names the version. Use it in a Dockerfile or a CI job, where a pinned URL is easier to audit than a flag:
# a fixed version curl -sSL https://github.com/astronomer/astro-cli/releases/download/v1.45.0/install.sh | sudo bash -s -- -b /usr/local/bin # whichever version is newest curl -sSL https://github.com/astronomer/astro-cli/releases/latest/download/install.sh | sudo bash -s -- -b /usr/local/bin
To install without sudo, pass a directory you can write to, such as -b ~/.local/bin.
Do not fetch godownloader.sh from a Git tag. That copy carries the version that was current when the release branch was cut, which is the release before the tag. Use the install.sh asset to pin a version.
If the install directory is missing or not writable, the installer says so and names the directory. Set
ASTRO_INSTALL_DIRto install somewhere else, or run it withsudofor/usr/local/bin.
If you encounter issues when installing the Astro CLI:
Make sure Docker Desktop is installed correctly. See [Install Docker Desktop on Windows]https://docs.docker.com/desktop/install/windows-install/).
Make sure the Docker Desktop WSL 2 backend is installed and configured correctly. See Docker Desktop WSL 2 backend.
Enable Hyper-V on the Docker and Linux Containers and run the Astro CLI natively. For additional information, see the Docker docs troubleshooting guide.
Create a project
$ mkdir hello-astro && cd hello-astro
$ astro dev init
Install the binary and Confirm the install worked:
$ ./astro
This generates a basic project directory:
.
├── dags
│ ├── exampledag.py
├── tests
│ ├── dags
│ ├── test_dag_example.py
├── Dockerfile
├── include
├── packages.txt
├── plugins
└── requirements.txt
Dags can go in the dags folder, custom Airflow plugins in plugins, python packages needed can go in requirements.txt, and OS level packages can go in packages.txt.
Run astro dev start to start a local version of airflow on your machine. This will spin up a few locally running docker containers - one for the airflow scheduler, one for the webserver, and one for postgres.
(Run astro dev ps to verify).
Astro CLI versions are released regularly and use semantic versioning. Backwards compatibility between versions cannot be guaranteed. Compatibility is only guaranteed between matching minor versions of the platform and the Astro CLI. For example, Astro CLI 0.9.0` is guaranteed to be compatible with houston-api v0.9.x, but not houston-api v0.10.x.
Astronomer ships major, minor, and patch releases of the Astro CLI in the following format:
{MAJOR_RELEASE}.{MINOR_RELEASE}.{PATCH_RELEASE}
All Astro CLI releases prior to 1.0.0 are considered beta.
Change log between each version can be found on the releases page
The Astro CLI includes a debug flag that allows you to view queries and internal logs. To enable it, you can pass --verbosity=debug in your commands, or you can add the following entry to your ~/.astro/config.yaml file:
verbosity: debug
Adding this entry to your ~/.astro/config.yaml file turns on debugging for all requests until you change it to info, or you remove it from the file.
To resolve an issue, Astronomer recommends reviewing the Astronomer documentation first.
If you're unable to resolve your issue after reviewing the documentation, you can post a question on the Astronomer web forum or you can contact Astronomer support.
Apache 2.0 with Commons Clause