The Astro CLI

If you have run next dev you already know the pattern. Astro ships a single astro binary that handles every stage of the development lifecycle — development server, production build, local preview, integration scaffolding, and type checking. It maps almost exactly to the Next.js CLI commands you already use daily.

Core commands

# Start the dev server (hot module reloading, port 4321 by default)
npx astro dev

# Production build → dist/
npx astro build

# Serve the dist/ folder locally (mirrors the production build exactly)
npx astro preview

# Add an official integration and update astro.config.mjs automatically
npx astro add react
npx astro add tailwind
npx astro add sitemap

# Type-check all .astro and .ts files
npx astro check

package.json scripts

Both frameworks follow the same convention of aliasing the CLI commands to short script names.

// package.json — Next.js project
{
  "scripts": {
    "dev":         "next dev",
    "build":       "next build",
    "start":       "next start",
    "lint":        "next lint",
    "type-check":  "tsc --noEmit"
  }
}

// package.json — Astro project
{
  "scripts": {
    "dev":     "astro dev",
    "build":   "astro build",
    "preview": "astro preview",
    "check":   "astro check"
  }
}

Two things stand out:

astro preview is the local preview server — it is not a production server. Use an adapter (Node, Vercel, Cloudflare) for real production SSR.
astro check replaces the two-step tsc --noEmit + linter that Next.js projects typically maintain separately.

The `astro add` command

npx astro add scaffolds official integrations in one step: it installs the npm package, updates astro.config.mjs, and prints what changed.

# Add the React integration (enables .tsx islands)
npx astro add react

# Add Tailwind CSS
npx astro add tailwind

# Add the Vercel SSR adapter
npx astro add vercel

# Add multiple at once
npx astro add react tailwind sitemap

There is no Next.js equivalent for this — in Next you npm install a package, then manually update next.config.js. The astro add command automates the config step.

CLI flags

# Custom port
astro dev --port 3000

# Bind to all interfaces (useful in Docker / WSL)
astro dev --host

# Verbose output during build
astro build --verbose

# Watch mode for astro check (re-runs on file save)
astro check --watch

Upgrading: Astro 5 → 7

npx @astrojs/upgrade bumps astro and every @astrojs/* integration to their latest majors. Then walk this checklist (it covers both the v6 and v7 breaking changes):

Node 22.12+ is required (Astro 7 ships Vite 8 with the Rolldown bundler).
Content collections: every collection needs a loader (glob()/file() from astro/loaders); entry.slug → entry.id; entry.render() → render(entry); import z from astro/zod.
Removed APIs: Astro.glob() → import.meta.glob(); <ViewTransitions /> → <ClientRouter />; prefetch(url, { with }) → prefetch(url); session drivers use sessionDrivers.redis({...}) objects, not strings.
Config flags: delete experimental.cache, experimental.routeRules, experimental.rustCompiler, experimental.queuedRendering, experimental.advancedRouting, experimental.logger — they are top-level or default now.
Templates: fix unclosed/mis-nested tags (the Rust compiler errors instead of auto-correcting) and add {" "} where you relied on newline whitespace (compressHTML: 'jsx' is the default).
Markdown: Sätteri is the default processor; keep remark/rehype plugins by setting markdown.processor: unified() from @astrojs/markdown-remark.
Gone for good: @astrojs/db (use node:sqlite, Drizzle, or a hosted DB) and the astro:transitions event constants (use the string event names).