CLI Commands

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

Using the CLI

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.

npm

npx astro dev

pnpm

pnpm astro dev

yarn

yarn astro dev

Available Commands

`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. Keyboard shortcuts:

s + enter - sync the content layer data (content and types)
o + enter - open your Astro site in the browser
q + enter - quit the development server

Example:

astro dev

Flags:

--port

number

default:"4321"

Specify which port to run on.

astro dev --port 8080

--host

string | boolean

Listen on all addresses, including LAN and public addresses. Pass a custom address to expose on a specific network IP.

# Listen on all addresses
astro dev --host

# Expose on specific address
astro dev --host 192.168.0.1

--open

string | boolean

Automatically open the app in the browser on server start. Can be passed a full URL or pathname.

astro dev --open
astro dev --open /about

--force

boolean

Clear the content layer cache, forcing a full rebuild.

astro dev --force

`astro build`

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. Example:

astro build

Flags:

--devOutput

boolean

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 build --devOutput

`astro preview`

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. Keyboard shortcuts:

o + enter - open your Astro site in the browser
q + enter - quit the preview server

Example:

astro preview

`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. Example:

astro check

Flags:

--watch

boolean

The command will watch for any changes in your project, and will report any errors.

astro check --watch

--root

string

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

astro check --root ./my-project

--tsconfig

string

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.

astro check --tsconfig ./tsconfig.custom.json

--minimumFailingSeverity

'error' | 'warning' | 'hint'

default:"'error'"

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

astro check --minimumFailingSeverity warning

--minimumSeverity

'error' | 'warning' | 'hint'

default:"'hint'"

Specifies the minimum severity to output.

astro check --minimumSeverity warning

--preserveWatchOutput

boolean

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

astro check --watch --preserveWatchOutput

--noSync

boolean

Specifies not to run astro sync before checking the project.

astro check --noSync

`astro sync`

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 Astro Env
The astro:actions module for Astro Actions

Running astro dev, astro build or astro check will run the sync command as well.

Example:

astro sync

`astro add`

Adds an integration to your configuration. This command will:

Install the necessary dependencies
Update your astro.config.mjs file
Apply any necessary configuration changes

Example:

# Add a single integration
astro add react

# Add multiple integrations
astro add react tailwind

`astro docs`

Launches the Astro Docs website directly from the terminal. Example:

astro docs

`astro info`

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

astro info

Example output:

Astro                    v5.14.1
Vite                     v6.3.6
Node                     v22.17.1
System                   macOS (arm64)
Package Manager          npm
Output                   static
Adapter                  none
Integrations             @astrojs/starlight (v0.35.3)

Flags:

--copy

boolean

The command will copy the output to the clipboard without prompting.

astro info --copy

`astro preferences`

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. 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)

Examples:

astro preferences list

`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. Examples:

astro telemetry disable

To disable telemetry in CI environments, add the astro telemetry disable command to your CI scripts or set the ASTRO_TELEMETRY_DISABLED environment variable.

`astro create-key`

Generates a key to encrypt props passed to server islands. Example:

astro create-key

Set this key as the ASTRO_KEY environment variable (e.g. in a .env file) and include it in your CI/CD or host’s build settings when you need a constant encryption key for your server islands for situations like rolling deployments, multi-region hosting or a CDN that caches pages containing server islands.

Global Flags

These flags can be used with any command.

--root

string

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

astro --root myRootFolder/myProjectFolder dev

--config

string

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

string

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

astro build --site https://example.com

--base

string

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

astro build --base /docs

--port

number

default:"4321"

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

astro dev --port 8080

--host

string | boolean

Sets which network IP addresses the dev server and preview server should listen on (i.e. non-localhost IPs).

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

astro dev --host
astro dev --host 192.168.0.1

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.

--allowed-hosts

string

Specifies the hostnames that Astro is allowed to respond to in dev or preview modes. Can be passed a comma-separated list of hostnames or true to allow any hostname.

astro dev --allowed-hosts staging.example.com,qa.example.com

--open

string | boolean

Automatically opens the app in the browser on server start. Can be passed a full URL string or a pathname.

astro dev --open
astro dev --open http://example.com
astro dev --open /about

--outDir

string

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

astro build --outDir ./custom-build

--force

string

Clear the content layer cache, forcing a full rebuild.

astro build --force

--mode

string

Configures the mode inline config for your project.

astro build --mode production

--verbose

boolean

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

astro build --verbose

--silent

boolean

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

astro dev --silent

--version

boolean

Prints the Astro version number and exits.

astro --version

--help

boolean

Prints the help message and exits.

astro --help
astro dev --help

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. The following scripts for the most common astro commands are added for you automatically when you create a project using the create astro wizard:

package.json

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

When using npm, you need to add -- before flags:

npm

npm run dev -- --port 8080
npm run build -- --verbose

pnpm

pnpm dev --port 8080
pnpm build --verbose

yarn

yarn dev --port 8080
yarn build --verbose

Configuration

Runtime API

Developer APIs

CLI Commands

Using the CLI

Available Commands

`astro dev`

`astro build`

`astro preview`

`astro check`

`astro sync`

`astro add`

`astro docs`

`astro info`

`astro preferences`

`astro telemetry`

`astro create-key`

Global Flags

package.json Scripts

Configuration

Runtime API

Developer APIs

​Using the CLI

​Available Commands

​astro dev

​astro build

​astro preview

​astro check

​astro sync

​astro add

​astro docs

​astro info

​astro preferences

​astro telemetry

​astro create-key

​Global Flags

​package.json Scripts

Using the CLI

Available Commands

`astro dev`

`astro build`

`astro preview`

`astro check`

`astro sync`

`astro add`

`astro docs`

`astro info`

`astro preferences`

`astro telemetry`

`astro create-key`

Global Flags

package.json Scripts