CLI Reference

Complete reference for Astro CLI commands

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:

1. Install the integration package
2. Update your astro.config.mjs file
3. 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