Skip to main content

Configure the Astro CLI

Install the CLI


To use the Astro CLI on Mac, you must have:


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.

Upgrade the CLI

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

Uninstall the CLI

To uninstall the Astro CLI on Mac, run:

brew uninstall 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

To uninstall astrocloud on Mac, run:

brew uninstall astronomer/cloud/astrocloud

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:

  1. In your terminal, open your Astro project.

  2. 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/ and .astro/config.yaml.

Step 4: Migrate project configurations (Optional)

If you manually updated the .astrocloud/config.yaml file of an existing Astro project:

  1. In your terminal, open your Astro project.
  2. Copy the contents from .astrocloud/config.yaml into .astro/config.yaml.
  3. 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 | sudo bash -s
astro deploy ${{ secrets.DEPLOYMENT_ID }}