CLI Reference

The Astro CLI is the primary way to interact with your Astro project from the command line.

Usage

npx astro <command> [flags]

Commands

`astro dev`

Runs Astro’s development server. This starts a local HTTP server that serves your project with Hot Module Replacement (HMR).

astro dev

Flags:

--port

number

default:"4321"

Specifies which port to run on. If the port is already in use, Astro will automatically try the next available port.

astro dev --port 8080

--host

string | boolean

Sets which network IP addresses the dev server should listen on (i.e. non-localhost IPs). Use --host to expose the server on all addresses, or pass a specific IP.

astro dev --host
astro dev --host 192.168.0.1

--open

string | boolean

Opens the app in a browser on server start. Pass a URL path (e.g. --open /about) to open to a specific page.

astro dev --open
astro dev --open /blog

--allowedHosts

string

Comma-separated list of allowed hostnames for the dev server.

astro dev --allowedHosts "staging.example.com,qa.example.com"

`astro build`

Builds your site for production. 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.

astro build

Flags:

--outDir

string

Specifies the output directory for the build. Overrides the outDir config option.

astro build --outDir ./custom-build

`astro preview`

Starts a local server to serve your built dist/ directory. This is useful for previewing your build locally, before deploying it.

astro preview

Flags:

--port

number

default:"4321"

Specifies which port to run on.

astro preview --port 8080

--host

string | boolean

Sets which network IP addresses the preview server should listen on.

astro preview --host

--open

string | boolean

Opens the app in a browser on server start.

astro preview --open

`astro check`

Runs diagnostics (such as type-checking .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.

astro check

Flags:

--watch

Runs the type checker in watch mode, re-checking files when they change.

astro check --watch

`astro sync`

Generates TypeScript types for all Astro modules. This sets up type stubs for content collections, environment variables, and other Astro features.

astro sync

`astro add`

Adds an integration to your Astro project. This command will:

Install the integration package
Update your astro.config.mjs file
Install any peer dependencies

astro add <integration>

Examples:

# Add a single integration
astro add react

# Add multiple integrations
astro add react tailwind

# Add an adapter
astro add netlify

Common integrations:

react - React support
vue - Vue support
svelte - Svelte support
solid-js - Solid support
preact - Preact support
mdx - MDX support
tailwind - Tailwind CSS support
sitemap - Sitemap generation
partytown - Partytown integration

Common adapters:

netlify - Deploy to Netlify
vercel - Deploy to Vercel
cloudflare - Deploy to Cloudflare
node - Deploy to Node.js servers
deno - Deploy to Deno Deploy

`astro docs`

Opens the Astro documentation website directly from your terminal.

astro docs

`astro info`

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

astro info

Outputs information like:

Astro version
Node version
Package manager
Operating system
Installed integrations

Flags:

--copy

Automatically copies the info output to your clipboard.

astro info --copy

`astro preferences`

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

astro preferences <command>

Commands:

# List all preferences and their current values
astro preferences list

# Enable a preference
astro preferences enable devToolbar

# Disable a preference
astro preferences disable devToolbar

# Reset a preference to its default
astro preferences reset devToolbar

# Get the current value of a preference
astro preferences get devToolbar

Available preferences:

devToolbar - Enable or disable the dev toolbar

Flags:

--global

Set preferences globally for all Astro projects on your machine.

astro preferences disable devToolbar --global

`astro telemetry`

Sets telemetry configuration for the current CLI user. Telemetry is anonymous data that provides insights into which Astro features are most used.

astro telemetry <command>

Commands:

# Enable telemetry
astro telemetry enable

# Disable telemetry
astro telemetry disable

# Reset telemetry settings
astro telemetry reset

`astro db`

Commands for managing Astro DB. These commands require the @astrojs/db integration to be installed.

astro db <command>

Commands:

# Push database schema to remote database
astro db push

# Pull remote database to local
astro db pull

# View database schema
astro db verify

See the Astro DB documentation for more details.

Global Flags

These flags are available for all commands:

`--config`

--config

string

Specifies the path to the config file. Defaults to astro.config.mjs.

astro dev --config ./custom-config.mjs

`--root`

--root

string

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

astro dev --root ./my-project

`--site`

--site

string

Overrides the site configuration option.

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

`--base`

--base

string

Overrides the base configuration option.

astro build --base /docs

`--verbose`

--verbose

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

astro build --verbose

`--silent`

--silent

Enables silent logging, which will prevent all logging.

astro build --silent

`--version`

--version

Prints the Astro version number and exits.

astro --version

`--help`

--help

Prints help message and exits.

astro --help
astro dev --help

Environment Variables

The Astro CLI respects several environment variables:

`NODE_ENV`

Sets the environment mode. Defaults to development in astro dev, and production in astro build and astro preview.

NODE_ENV=production astro dev

`ASTRO_TELEMETRY_DISABLED`

When set to 1, disables telemetry collection.

ASTRO_TELEMETRY_DISABLED=1 astro dev

Examples

Development Workflow

# Start dev server
astro dev

# Start on custom port
astro dev --port 3000

# Expose to network
astro dev --host

# Open in browser
astro dev --open

Production Build

# Build for production
astro build

# Preview production build
astro preview

# Build with custom output directory
astro build --outDir ./build

Type Checking

# One-time type check
astro check

# Watch mode for continuous checking
astro check --watch

Adding Integrations

# Add React support
astro add react

# Add multiple integrations at once
astro add react tailwind mdx

# Add an adapter for deployment
astro add netlify

JavaScript API

Runtime API

Configuration

CLI Commands

CLI Reference

Usage

Commands

`astro dev`

`astro build`

`astro preview`

`astro check`

`astro sync`

`astro add`

`astro docs`

`astro info`

`astro preferences`

`astro telemetry`

`astro db`

Global Flags

`--config`

`--root`

`--site`

`--base`

`--verbose`

`--silent`

`--version`

`--help`

Environment Variables

`NODE_ENV`

`ASTRO_TELEMETRY_DISABLED`

Examples

Development Workflow

Production Build

Type Checking

Adding Integrations

Build docs developers (and LLMs) love

JavaScript API

Runtime API

Configuration

CLI Commands

​Usage

​Commands

​astro dev

​astro build

​astro preview

​astro check

​astro sync

​astro add

​astro docs

​astro info

​astro preferences

​astro telemetry

​astro db

​Global Flags

​--config

​--root

​--site

​--base

​--verbose

​--silent

​--version

​--help

​Environment Variables

​NODE_ENV

​ASTRO_TELEMETRY_DISABLED

​Examples

​Development Workflow

​Production Build

​Type Checking

​Adding Integrations

Build docs developers (and LLMs) love

Usage

Commands

`astro dev`

`astro build`

`astro preview`

`astro check`

`astro sync`

`astro add`

`astro docs`

`astro info`

`astro preferences`

`astro telemetry`

`astro db`

Global Flags

`--config`

`--root`

`--site`

`--base`

`--verbose`

`--silent`

`--version`

`--help`

Environment Variables

`NODE_ENV`

`ASTRO_TELEMETRY_DISABLED`

Examples

Development Workflow

Production Build

Type Checking

Adding Integrations