You can use the Command-Line Interface (CLI) provided by Astro to develop, build, and preview your project from a terminal window.
Section titled astro commands
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:
You can type
astro --help in your terminal to display a list of all available commands:
The following message will display in your terminal:
Section titled package.json scripts
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 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.
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.
Section titled astro dev
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.
Use these flags to customize the behavior of the Astro dev server. For flags shared with other Astro commands, see common flags below.
Section titled --port <number>
Specifies which port to run on. Defaults to
Section titled --host [optional host address]
--host [optional host address]
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
Section titled astro build
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.
Use these flags to customize your build. For flags shared with other Astro commands, see common flags below.
Section titled astro preview
Starts a local server to serve your static
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
Can be combined with the common flags documented below.
Section titled astro check
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.
Use these flags to customize the behavior of the command.
Section titled --watch
The command will watch for any changes to
.astro files, and will report any errors.
📚 Read more about TypeScript support in Astro.
Section titled astro sync
Section titled astro add
Adds an integration to your configuration. Read more in the integrations guide.
Section titled astro docs
Launches the Astro Docs website directly from the terminal.
Section titled astro info
Reports useful information about your current Astro environment. Useful for providing information when opening an issue.
Section titled astro telemetry
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:
Telemetry can later be re-enabled with:
clear command resets the telemetry data:
Common flagsSection titled Common flags
Section titled --root <path>
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.
Section titled --config <path>
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.
Section titled --site <url>
site for your project. Passing this flag will override the
site value in your
astro.config.mjs file, if one exists.
Section titled --base <pathname>
base for your project. Passing this flag will override the
base value in your
astro.config.mjs file, if one exists.
Section titled --verbose
Enables verbose logging, which is helpful when debugging an issue.
Section titled --silent
Enables silent logging, which will run the server without any console output.
Global flagsSection titled Global flags
Use these flags to get information about the
Section titled --version
Prints the Astro version number and exits.
Section titled --open
Automatically opens the app in the browser on server start.
Section titled --help
Prints the help message and exits.
Advanced APIs (Experimental)Section titled Advanced APIs (Experimental)
If you need more control when running Astro, the
"astro" package also exports APIs to programmatically run the CLI commands.
These APIs are experimental and their API signature may change. Any updates will be mentioned in the Astro changelog and the information below will always show the current, up-to-date information.
Section titled AstroInlineConfig
AstroInlineConfig type is used by all of the command APIs below. It extends from the user Astro config type:
Section titled configFile
string | false
A custom path to the Astro config file.
If this value is undefined (default) or unset, Astro will search for an
astro.config.(js,mjs,ts) file relative to the
root and load the config file if found.
If a relative path is set, it will resolve based on the current working directory.
false to disable loading any config files.
The inline config passed in this object will take highest priority when merging with the loaded user config.
"development" | "production"
"development" when running
"production" when running
The mode used when building your site to generate either “development” or “production” code.
Section titled logLevel
"debug" | "info" | "warn" | "error" | "silent"
The logging level to filter messages logged by Astro.
"debug": Log everything, including noisy debugging diagnostics.
"info": Log informational messages, warnings, and errors.
"warn": Log warnings and errors.
"error": Log errors only.
"silent": No logging.
Section titled dev()
(inlineConfig: AstroInlineConfig) => AstroDevServer
astro dev, it runs Astro’s development server.
Section titled build()
(inlineConfig: AstroInlineConfig) => void
astro build, it builds your site for deployment.
Section titled preview()
(inlineConfig: AstroInlineConfig) => AstroPreviewServer
astro preview, it starts a local server to serve your static
Section titled sync()
(inlineConfig: AstroInlineConfig) => number
astro sync, it generates TypeScript types for all Astro modules