Configure the Astro CLI
Install the CLI
- Mac
- Windows
- Linux
Prerequisites
To use the Astro CLI on Mac, you must have:
- Homebrew
- Docker Desktop (v18.09 or higher).
Installation
To install the latest version of the Astro CLI, run the following command:
brew install astro
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>
If you specify only a major version, this command installs the latest minor or patch version available for the major version.
Prerequisites
To use the Astro CLI on Windows, you must have:
- Docker Desktop for Windows.
- Docker Engine (v0.18.9 or higher).
- WSL enabled on your local machine.
- Windows 10 or Windows 11.
Installation
Go to the Releases page of the Astro CLI GitHub repository. Based on your desired CLI version and the CPU architecture of your machine, download one of the
.zip
files available on this page.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.zip
.If the
.zip
file does not automatically unzip, run the following command to unzip the executable:tar -xvzf .\astrocli.tar.gz
Add the filepath for the directory containing
astro.exe
as a PATH environment variable. For example, ifastro.exe
was stored inC:\Users\username\astro.exe
, you would addC:\Users\username
as your PATH environment variable. To learn more about configuring the PATH environment variable, see Java documentation.Restart your machine.
Prerequisites
To use the Astro CLI on Linux, you must have:
- Docker Engine (v0.18.9 or higher).
Installation
Run the following command to install the latest version of the Astro CLI directly to PATH
:
curl -sSL install.astronomer.io | sudo bash -s
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 | sudo bash -s -- v1.1.0
If you specify only a major version, this command installs the latest minor or patch version available for the major version.
Upgrade the CLI
- Mac
- Windows
- Linux
To upgrade the Astro CLI to the latest version, you can run the same command as you did to install the CLI for the first time:
brew install astro
To upgrade the Astro CLI on Windows:
Delete the existing
astro.exe
file on your machine.Go to the Releases page of the Astro CLI GitHub repository. Based on the version of the CLI you want and your CPU architecture, download one of the
.zip
files available on this page.For example, to upgrade to v1.0.0 of the Astro CLI on a Windows machine with an AMD 64 architecture, you download
astro_1.0.0-converged_windows_amd64.zip
.If the
.zip
file does not automatically unzip, run the following command to unzip the executable:tar -xvzf .\astrocli.tar.gz
Add the filepath for the directory containing the new
astro.exe
as a PATH environment variable. For example, ifastro.exe
was stored inC:\Users\username\astro.exe
, you would addC:\Users\username
as your PATH environment variable. To learn more about configuring the PATH environment variable, see Java documentation.Restart your machine.
To upgrade to the latest version of the Astro CLI, run:
curl -sSL install.astronomer.io | sudo bash -s
Uninstall the CLI
- Mac
- Windows
- Linux
To uninstall the Astro CLI on Mac, run:
brew uninstall astro
To uninstall the Astro CLI on Windows:
- Delete the filepath for
astro.exe
from your Windows PATH environment variable. - Delete
astro.exe
.
To uninstall the Astro CLI on Linux, run the following command:
sudo rm /usr/local/bin/astro
Migrate from astrocloud
to astro
A new astro
executable for the Astro CLI is now available. Complete this migration if all of the following are true:
- You are an Astro user.
- You're currently using the
astrocloud
CLI executable.
For more information on Astro CLI v1.0.0, see Astro CLI Release Notes.
Step 1: Uninstall astrocloud
- Mac
- Windows
- Linux
To uninstall astrocloud
on Mac, run:
brew uninstall astronomer/cloud/astrocloud
To uninstall astrocloud
on Windows:
- Delete the filepath for
astrocloud.exe
from your Windows PATH environment variable. - Delete
astrocloud.exe
from your machine.
To uninstall astrocloud
on Linux:
- Delete the filepath for
astrocloud.exe
from your Linux PATH environment variable. - Delete
astrocloud.exe
from your machine.
Step 2: Install Astro CLI v1.0+
Once you've uninstalled the astrocloud
executable, install the latest version of astro
on your machine.
For instructions, see Install the CLI.
Step 3: Migrate existing Astro projects
In order to run and deploy your existing Astro projects using the astro
executable, you need to populate these projects with a new .astro
directory of files. For any existing Astro projects on your machine:
In your terminal, open your Astro project.
Run
astro dev init
to generate a new.astro
directory in your project. This subdirectory might be hidden in graphical file browsers. You can show hidden files using⌘ + Shift + .
on Mac or by selecting View > Hidden items in Windows file explorer.If the CLI prompts you about whether you want to create a project in a non-empty directory, enter
Yes
. The CLI will only create files that aren't yet in your directory. In this case, the only files that it creates are./astro/test_dag_integrity_default.py
and.astro/config.yaml
.
Step 4: Migrate project configurations (Optional)
If you manually updated the .astrocloud/config.yaml
file of an existing Astro project:
- In your terminal, open your Astro project.
- Copy the contents from
.astrocloud/config.yaml
into.astro/config.yaml
. - Delete
.astrocloud/config.yaml
from your project.
Step 5: Update CI/CD pipelines (Optional)
If you have an existing CI/CD pipeline using the old astrocloud
executable, update it to use astro
. For example, in a GitHub Actions CI/CD pipeline you would update the following:
# Before:
- name: Deploy to Astro
run: |
brew install astronomer/cloud/astrocloud
astrocloud deploy ${{ secrets.DEPLOYMENT_ID }}
# After:
- name: Deploy to Astro
run: |
curl -sSL install.astronomer.io | sudo bash -s
astro deploy ${{ secrets.DEPLOYMENT_ID }}