CLI Commands

You can use the Command-Line Interface (CLI) provided by Astro to develop, build, and preview your project from a terminal window.

Use the CLI by running one of the commands documented on this page with your preferred package manager, optionally followed by any flags. Flags customize the behavior of a command.

One of the commands you’ll use most often is astro dev. This command starts the development server and gives you a live, updating preview of your site in a browser as you work:

# start the development server
npx astro dev

# start the development server
pnpm astro dev

# start the development server
yarn astro dev

You can type astro --help in your terminal to display a list of all available commands:

npx astro --help

pnpm astro --help

yarn astro --help

The following message will display in your terminal:

astro [command] [...flags]

Commands
              add  Add an integration.
            build  Build your project and write it to disk.
            check  Check your project for errors.
              dev  Start the development server.
             docs  Open documentation in your web browser.
             info  List info about your current Astro setup.
          preview  Preview your build locally.
             sync  Generate content collection types.
        telemetry  Configure telemetry settings.

Global Flags
  --config <path>  Specify your config file.
    --root <path>  Specify your project root folder.
     --site <url>  Specify your project site.
--base <pathname>  Specify your project base.
        --verbose  Enable verbose logging.
         --silent  Disable all logging.
        --version  Show the version number and exit.
           --open  Open the app in the browser on server start.
           --help  Show this help message.

You can also use scripts in package.json for shorter versions of these commands. Using a script allows you to use the same commands that you may be familiar with from other projects, such as npm run build.

The following scripts for the most common astro commands (astro dev, astro build, and astro preview) are added for you automatically when you create a project using the create astro wizard.

When you follow the instructions to install Astro manually, you are instructed to add these scripts yourself. You can also add more scripts to this list manually for any commands you use frequently.

{
  "scripts": {
    "dev": "astro dev",
    "start": "astro dev",
    "build": "astro build",
    "preview": "astro preview"
  }
}

You will often use these astro commands, or the scripts that run them, without any flags. Add flags to the command when you want to customize the command’s behavior. For example, you may wish to start the development server on a different port, or build your site including draft pages.

# run the dev server on port 8080 using the `start` script in `package.json`
npm run start -- --port 8080

# build your site including draft pages using the `build` script in `package.json`
npm run build -- --drafts

# run the dev server on port 8080 using the `start` script in `package.json`
pnpm start --port 8080

# build your site including draft pages using the `build` script in `package.json`
pnpm build --drafts

# run the dev server on port 8080 using the `start` script in `package.json`
yarn start --port 8080

# build your site including draft pages using the `build` script in `package.json`
yarn build --drafts

Runs Astro’s development server. This is a local HTTP server that doesn’t bundle assets. It uses Hot Module Replacement (HMR) to update your browser as you save changes in your editor.

Flags

Use these flags to customize the behavior of the Astro dev server. For flags shared with other Astro commands, see common flags below.

Specifies which port to run on. Defaults to 3000.

Sets which network IP addresses the dev server should listen on (i.e. non-localhost IPs). This can be useful for testing your project on local devices like a mobile phone during development.

• --host — listen on all addresses, including LAN and public addresses
• --host <custom-address> — expose on a network IP address at <custom-address>

Builds your site for deployment. By default, this will generate static files and place them in a dist/ directory. If SSR is enabled, this will generate the necessary server files to serve your site.

Flags

Use these flags to customize your build. For flags shared with other Astro commands, see common flags below.

Includes Markdown draft pages in the build.

Starts a local server to serve your static dist/ directory.

This command is useful for previewing your build locally, before deploying it. It is not designed to be run in production. For help with production hosting, check out our guide on Deploying an Astro Website.

Since Astro 1.5.0, astro preview also works for SSR builds if you use an adapter that supports it. Currently, only the Node adapter supports astro preview.

Can be combined with the common flags documented below.

Runs diagnostics (such as type-checking within .astro files) against your project and reports errors to the console. If any errors are found the process will exit with a code of 1.

This command is intended to be used in CI workflows.

Flags

Use these flags to customize the behavior of the command.

The command will watch for any changes to .astro files, and will report any errors.

📚 Read more about TypeScript support in Astro.

Added in: astro@2.0.0

Generates TypeScript types for all Astro modules. This sets up a src/env.d.ts file for type inferencing, and defines the astro:content module for the Content Collections API.

Adds an integration to your configuration. Read more in the integrations guide.

Launches the Astro Docs website directly from the terminal.

Reports useful information about your current Astro environment. Useful for providing information when opening an issue.

astro info

Example output:

Astro version            v2.6.6
Package manager          pnpm
Platform                 darwin
Architecture             arm64
Adapter                  @astrojs/vercel/serverless
Integrations             None or couldn't determine.

Sets telemetry configuration for the current CLI user. Telemetry is anonymous data that provides the Astro team insights into which Astro features are most often used.

Telemetry can be disabled with this CLI command:

astro telemetry disable

Telemetry can later be re-enabled with:

astro telemetry enable

The clear command resets the telemetry data:

astro telemetry clear

Specifies the path to the project root. If not specified, the current working directory is assumed to be the root.

The root is used for finding the Astro configuration file.

astro --root myRootFolder/myProjectFolder dev

Specifies the path to the config file relative to the project root. Defaults to astro.config.mjs. Use this if you use a different name for your configuration file or have your config file in another folder.

astro --config config/astro.config.mjs dev

Configures the site for your project. Passing this flag will override the site value in your astro.config.mjs file, if one exists.

Configures the base for your project. Passing this flag will override the base value in your astro.config.mjs file, if one exists.

Enables verbose logging, which is helpful when debugging an issue.

Enables silent logging, which will run the server without any console output.

Use these flags to get information about the astro CLI.

Prints the Astro version number and exits.

Automatically opens the app in the browser on server start.

Prints the help message and exits.