CLI Reference
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, optionally followed by any flags. Flags customize the behavior of a command. For example, to start the development server on port 8080
, you would combine the astro dev
command with the --port
flag: astro dev --port 8080
.
In most cases you will use the CLI via your package manager:
npx astro dev --port 8080
pnpm astro dev --port 8080
yarn astro dev --port 8080
If you started your project using the create astro
wizard, you can also use the scripts in package.json
for a shorter version of these commands. See the README.md
in your project for details of which commands are available.
# run the dev server on port 8080 using the `start` script in `package.json`
pnpm start --port 8080
# run the dev server on port 8080 using the `start` script in `package.json`
yarn start --port 8080
# run the dev server on port 8080 using the `start` script in `package.json`
npm run start -- --port 8080
(The extra --
before the --port
flag is necessary for npm
to pass your flags to the astro
command.)
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.
Flags
Use these flags to customize the behavior of the Astro dev server. For flags shared with other Astro commands, see common flags below.
--port <number>
Section titled --port <number>Specifies which port to run on. Defaults to 3000
.
--host [optional host address]
Section titled --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<custom-address>
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 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.
--drafts
Section titled --draftsIncludes Markdown draft pages in the build.
astro preview
Section titled astro previewStarts 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.
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.
📚 Read more about TypeScript support in Astro.
astro sync
Section titled astro syncAdded in: v2.0.0 Beta
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.
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 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.
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
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.
astro --root myRootFolder/myProjectFolder dev
--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.
astro --config config/astro.config.mjs dev
--site
Section titled --siteConfigures the site
for your project. Passing this flag will override the site
value in your astro.config.mjs
file, if one exists.
--base
Section titled --baseConfigures the base
for your project. Passing this flag will override the base
value in your astro.config.mjs
file, if one exists.
--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.
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.