Skip to content

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:

Terminal window
# start the development server
npx astro dev

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

Terminal window
npx astro --help

The following message will display in your terminal:

Terminal window
astro [command] [...flags]
Commands
add Add an integration.
build Build your project and write it to disk.
check Check your project for errors.
create-key Create a cryptography key
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 TypeScript types for all Astro modules.
preferences Configure user preferences.
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.
--help Show this help message.

You can add the --help flag after any command to get a list of all the flags for that command.

Terminal window
# get a list of all flags for the `dev` command
npm run dev -- --help

The following message will display in your terminal:

Terminal window
astro dev [...flags]
Flags
--port Specify which port to run on. Defaults to 4321.
--host Listen on all addresses, including LAN and public addresses.
--host <custom-address> Expose on a network IP address at <custom-address>
--open Automatically open the app in the browser on server start
--force Clear the content layer cache, forcing a full rebuild.
--help (-h) See all available flags.

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.

package.json
{
"scripts": {
"dev": "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 with verbose logs for debugging.

Terminal window
# run the dev server on port 8080 using the `start` script in `package.json`
npm run dev -- --port 8080
# build your site with verbose logs using the `build` script in `package.json`
npm run build -- --verbose

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.

Builds your site for deployment. By default, this will generate static files and place them in a dist/ directory. If any routes are rendered on demand, this will generate the necessary server files to serve your site.

The command accepts common flags and the following additional flags:

Added in: astro@5.0.0 New

Outputs a development-based build similar to code transformed in astro dev. This can be useful to test build-only issues with additional debugging information included.

Starts a local server to serve the contents of your static directory (dist/ by default) created by running astro build.

This command allows you to preview your site locally after building to catch any errors in your build output 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, the Node adapter supports astro preview for builds generated with on-demand rendering.

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 in your project, and will report any errors.

Specifies a different root directory to check. Uses the current working directory by default.

Specifies a tsconfig.json file to use manually. If not provided, Astro will attempt to find a config, or infer the project’s config automatically.

--minimumFailingSeverity <error|warning|hint>

Section titled --minimumFailingSeverity &lt;error|warning|hint&gt;

Specifies the minimum severity needed to exit with an error code. Defaults to error.

For example, running astro check --minimumFailingSeverity warning will cause the command to exit with an error if any warnings are detected.

Specifies the minimum severity to output. Defaults to hint.

For example, running astro check --minimumSeverity warning will show errors and warning, but not hints.

Specifies not to clear the ouput between checks when in watch mode.

Specifies not to run astro sync before checking the project.

Read more about type checking in Astro.

Added in: astro@2.0.0

Generates TypeScript types for all Astro modules. This sets up a .astro/types.d.ts file for type inferencing, and defines modules for features that rely on generated types:

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.

Terminal window
astro info

Example output:

Astro v3.0.12
Node v20.5.1
System macOS (arm64)
Package Manager pnpm
Output server
Adapter @astrojs/vercel/serverless
Integrations none

Manage user preferences with the astro preferences command. User preferences are specific to individual Astro users, unlike the astro.config.mjs file which changes behavior for everyone working on a project.

User preferences are scoped to the current project by default, stored in a local .astro/settings.json file.

Using the --global flag, user preferences can also be applied to every Astro project on the current machine. Global user preferences are stored in an operating system-specific location.

Available preferences

  • devToolbar — Enable or disable the development toolbar in the browser. (Default: true)
  • checkUpdates — Enable or disable automatic update checks for the Astro CLI. (Default: true)

The list command prints the current settings of all configurable user preferences. It also supports a machine-readable --json output.

Terminal window
astro preferences list

Example terminal output:

PreferenceValue
devToolbar.enabledtrue
checkUpdates.enabledtrue

You can enable, disable, or reset preferences to their default.

For example, to disable the devToolbar in a specific Astro project:

Terminal window
astro preferences disable devToolbar

To disable the devToolbar in all Astro projects on the current machine:

Terminal window
astro preferences disable --global devToolbar

The devToolbar can later be enabled with:

Terminal window
astro preferences enable devToolbar

The reset command resets a preference to its default value:

Terminal window
astro preferences reset devToolbar

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. For more information see Astro’s telemetry page.

Telemetry can be disabled with this CLI command:

Terminal window
astro telemetry disable

Telemetry can later be re-enabled with:

Terminal window
astro telemetry enable

The reset command resets the telemetry data:

Terminal window
astro telemetry reset

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.

Terminal window
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.

Terminal window
astro --config config/astro.config.mjs dev

Added in: astro@5.0.0 New

Configures the mode inline config for your project.

Added in: astro@3.3.0

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

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

Added in: astro@1.4.1

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

Specifies which port to run the dev server and preview server on. Defaults to 4321.

--host [optional host address]

Section titled --host [optional host address]

Sets which network IP addresses the dev server and preview 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>

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

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

Automatically opens the app in the browser on server start. Can be passed a full URL string (e.g. --open http://example.com) or a pathname (e.g. --open /about) to specify the URL to open.

Use these flags to get information about the astro CLI.

Prints the Astro version number and exits.

Prints the help message and exits.

Contribute

What’s on your mind?

Create GitHub Issue

Quickest way to alert our team of a problem.

Community