Every Astro CLI Command You'll Actually Use

The Astro CLI has eleven commands in Astro 7, and day to day you’ll use five: astro dev to develop, astro build to produce the site, astro preview to test the build, astro check to catch type errors, and astro add to install integrations. Run them through npx astro <command> or the matching npm run scripts in package.json.

Key Takeaways

• npm run dev, npm run build and npm run preview map to astro dev, astro build and astro preview in every starter.
• npx astro add <name> installs an integration and edits your config for you.
• Run npx astro check in CI to fail builds on TypeScript and template errors.
• npx astro sync regenerates content collection types without starting the dev server.

The commands

Command	What it does
astro dev	Starts the dev server with hot reload at http://localhost:4321
astro build	Builds the site to dist/
astro preview	Serves the built dist/ locally
astro check	Type-checks .astro, .ts and framework files
astro add	Installs and configures an integration or adapter
astro sync	Generates types for content collections and astro:env
astro info	Prints Astro, Node, OS and integration versions
astro docs	Opens the Astro docs in your browser
astro preferences	Sets user preferences, such as toggling the dev toolbar
astro telemetry	Enables or disables anonymous telemetry
astro create-key	Creates a key for encrypting server island props

astro dev

npx astro dev
npx astro dev --port 3000
npx astro dev --host          # expose on your local network, e.g. to test on a phone
npx astro dev --open          # open the browser automatically

--host is the one people miss. Without it, the server only listens on localhost, so your phone on the same Wi-Fi can’t reach it.

astro build

npx astro build

Writes the production site to dist/ (or outDir). Static pages become HTML files, endpoints become files, and on-demand routes go into a server bundle if an adapter is installed. If a build fails, the first error in the output is the one to fix; later errors often follow from it.

astro preview

npx astro build && npx astro preview

Serves dist/ exactly as built. Use it before every deploy to catch issues the dev server hides, such as broken links to assets or a page that only works with hot reload. With some adapters, preview runs the adapter’s own server.

astro check

npx astro check

Runs diagnostics across .astro files, including typed props and template expressions. It needs @astrojs/check and typescript installed; the first run offers to add them. Add it to CI before the build:

{
  "scripts": {
    "check": "astro check",
    "build": "astro check && astro build"
  }
}

astro add

npx astro add react
npx astro add mdx sitemap
npx astro add cloudflare
npx astro add tailwind

Installs the package, then shows the config change and asks before writing it. You can pass several integrations at once. Use --yes to accept all prompts in scripts.

astro sync

npx astro sync

Generates the types for astro:content, astro:env and astro:actions. The dev server and build run it automatically, so you’ll mostly need it after changing src/content.config.ts while your editor shows stale types, or in CI before tsc.

astro info

npx astro info

Prints versions of Astro, Node.js, your package manager, OS, adapter and integrations. Paste the output into any bug report or support question; it answers the first five questions anyone will ask. Add --copy to put it on your clipboard.

Global flags

These work with most commands:

• --root <path> runs the command for a project in another folder.
• --config <path> uses a different config file.
• --site <url> and --base <path> override config values for one run.
• --verbose prints debug logs, useful when a build hangs.
• --silent hides all output.

Creating a project

create-astro is a separate package:

npm create astro@latest
npm create astro@latest -- --template blog

If you’re starting from a finished site instead, the getting started docs cover cloning and running a Komal theme. For what Astro does when you run these commands, read What is Astro?, and for shipping the build output, the Astro deploy guide. The full flag list is in the Astro CLI reference.

FAQ

What port does astro dev use?

Port 4321 by default. Change it with --port or server.port in astro.config.mjs.

What is the difference between astro dev and astro preview?

astro dev compiles on the fly with hot reload for development. astro preview serves the output of astro build to test the production result.