CLI Commands
You can use the Command-Line Interface (CLI) provided by Astro to develop, build, and preview your project from a terminal window.
astro
commands
Section titled astro commandsUse 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:
You can add the --help
flag after any command to get a list of all the flags for that command.
The following message will display in your terminal:
The extra --
before any flag is necessary for npm
to pass your flags to the astro
command.
package.json
scripts
Section titled package.json scriptsYou 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.
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.
astro dev
Section titled astro devRuns 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.
astro build
Section titled astro buildBuilds 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.
Flags
Section titled FlagsThe command accepts common flags and the following additional flags:
--devOutput
Section titled --devOutput
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.
astro preview
Section titled astro previewStarts 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.
astro check
Section titled astro checkRuns 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.
--watch
Section titled --watchThe command will watch for any changes in your project, and will report any errors.
--root <path-to-dir>
Section titled --root <path-to-dir>Specifies a different root directory to check. Uses the current working directory by default.
--tsconfig <path-to-file>
Section titled --tsconfig <path-to-file>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 <error|warning|hint>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.
--minimumSeverity <error|warning|hint>
Section titled --minimumSeverity <error|warning|hint>Specifies the minimum severity to output. Defaults to hint
.
For example, running astro check --minimumSeverity warning
will show errors and warning, but not hints.
--preserveWatchOutput
Section titled --preserveWatchOutputSpecifies not to clear the ouput between checks when in watch mode.
--noSync
Section titled --noSyncSpecifies not to run astro sync
before checking the project.
astro sync
Section titled astro sync
Added in:
astro@2.0.0
Running astro dev
, astro build
or astro check
will run the sync
command as well.
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:
- The
astro:content
module for the Content Collections API. - The
astro:db
module for Astro DB. - The
astro:env
module for experimental Astro Env. - The
astro:actions
module for Astro Actions
astro add
Section titled astro addAdds an integration to your configuration. Read more in the integrations guide.
astro docs
Section titled astro docsLaunches the Astro Docs website directly from the terminal.
astro info
Section titled astro infoReports useful information about your current Astro environment. Useful for providing information when opening an issue.
Example output:
astro preferences
Section titled astro preferencesManage 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.
Example terminal output:
Preference | Value |
---|---|
devToolbar.enabled | true |
checkUpdates.enabled | true |
You can enable
, disable
, or reset
preferences to their default.
For example, to disable the devToolbar in a specific Astro project:
To disable the devToolbar in all Astro projects on the current machine:
The devToolbar can later be enabled with:
The reset
command resets a preference to its default value:
astro telemetry
Section titled astro telemetrySets 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:
Telemetry can later be re-enabled with:
The reset
command resets the telemetry data:
Add the astro telemetry disable
command to your CI scripts or set the ASTRO_TELEMETRY_DISABLED
environment variable.
Common flags
Section titled Common flags--root <path>
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.
--config <path>
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.
--mode <string>
Section titled --mode <string>
Added in:
astro@5.0.0
New
Configures the mode
inline config for your project.
--outDir <path>
Section titled --outDir <path>
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.
--site <url>
Section titled --site <url>Configures the site
for your project. Passing this flag will override the site
value in your astro.config.mjs
file, if one exists.
--base <pathname>
Section titled --base <pathname>
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.
--port <number>
Section titled --port <number>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>
Do not use the --host
flag to expose the dev server and preview server in a production environment. The servers are designed for local use while developing your site only.
--verbose
Section titled --verboseEnables verbose logging, which is helpful when debugging an issue.
--silent
Section titled --silentEnables silent logging, which will run the server without any console output.
--open
Section titled --openAutomatically 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.
Global flags
Section titled Global flagsUse these flags to get information about the astro
CLI.
--version
Section titled --versionPrints the Astro version number and exits.
--help
Section titled --helpPrints the help message and exits.
Reference