CLI Reference

Purpose and Scope

The Astro command line interface is the project entry point for everyday terminal work after a site has been created. It starts the local development server, builds and previews output, adds integrations, checks project diagnostics, generates module types, prints environment information, and manages preferences such as telemetry. The public documentation frames the interface as a package-manager driven command surface, while the implementation routes parsed arguments to command modules inside the Astro package. This page explains that routing layer and the command behaviors visible in the provided sources so maintainers can connect user-facing syntax to implementation responsibilities.

Sources: packages/astro/src/cli/index.ts, packages/astro/src/cli/help/index.ts

The reference is intentionally focused on the astro binary rather than every tool in the repository. Project scaffolding is handled by the separate create workflow, and version-to-version migration is handled by the upgrade workflow, but the runtime commands documented here are the ones a project runs repeatedly during development and verification. When reading source or debugging a CLI bug, start with command resolution, then move to the specific command module, because the shared entrypoint decides whether a request displays help, prints a version, gathers debug information, or delegates to a feature command.

Sources: packages/astro/src/cli/index.ts

Relevant Source Files

• packages/astro/src/cli/infra/build-time-astro-version-provider.ts — supplies the Astro version string that is injected at build time and later used by version display logic.
• packages/astro/src/cli/add/index.ts — implements astro add, including integration and adapter aliases, help tables, config resolution, telemetry, package lookup, and configuration stubs.
• packages/astro/src/cli/check/index.ts — implements astro check, including required package acquisition, optional sync before diagnostics, and delegation to @astrojs/check.
• packages/astro/src/cli/dev/index.ts — implements astro dev, including help output, foreground and background server modes, lock-file protection, agent-aware JSON logging, and subcommands for stop, status, and logs.
• packages/astro/src/cli/help/index.ts — defines the default top-level help payload, command list, and global flag descriptions.
• packages/astro/src/cli/index.ts — parses and resolves supported commands, creates shared infrastructure, and dispatches to command-specific implementations.

Command Resolution and Top-Level Help

The central dispatcher recognizes a fixed set of command names and falls back to help when the request does not match a supported command. A version flag short-circuits normal command selection, which means version output is available even when no command name is supplied. The top-level help payload describes the command form as a command followed by flags, presents Astro’s headline, and lists the command families users see in terminal help. This separation keeps command discovery declarative while allowing command execution to stay lazy-loaded and command-specific.

Sources: packages/astro/src/cli/index.ts, packages/astro/src/cli/help/index.ts

The implementation creates shared services only after a command has been resolved. It dynamically imports logger creation, text styling, the build-time version provider, help display, and the command runner. That design matters for both startup behavior and maintenance: help and version commands can run without reading project configuration, while commands that need project context can import heavier modules later. The dispatcher also constructs the debug information path for astro info, assembling operating system, package manager, Node version, Astro config, formatting, prompting, and clipboard helpers before invoking the info command.

Sources: packages/astro/src/cli/index.ts, packages/astro/src/cli/infra/build-time-astro-version-provider.ts

Core Commands and Flags Reference

Command or flag	Source-backed behavior
astro add	Adds integrations or adapters, accepts names, supports --yes, and prints command-specific help when no names or help flags are supplied.
astro check	Loads @astrojs/check and typescript, optionally runs sync first, parses check options from process arguments, and returns diagnostics from the checker.
astro dev	Starts the development server, supports background mode, and exposes stop, status, and logs subcommands.
astro build	Recognized by the dispatcher as a supported command and listed in top-level help as the command that writes a build to disk.
astro preview	Recognized by the dispatcher and listed in top-level help as local build preview.
astro sync	Recognized by the dispatcher and listed in top-level help as content collection type generation.
astro info	Runs directly from the dispatcher after collecting debug context and formatting helpers.
astro telemetry	Recognized by the dispatcher and listed in top-level help as telemetry settings configuration.
--config, --root, --site, --base	Global flags in top-level help that influence configuration and project targeting.
--verbose, --silent, --json	Logging-related global flags described by the top-level help payload.
--version, --help	Direct discovery flags for version display and help output.

The table above separates resolved commands from behavior proven in the supplied implementation snippets. Some commands are visible through the dispatcher and help payload but have their detailed implementations outside this page’s source set. For those commands, the reliable contract here is that the top-level CLI recognizes the command and documents its public intent. For add, check, and dev, the requested source files show enough detail to describe argument handling, configuration interaction, package checks, logging behavior, and failure paths with more precision.

Sources: packages/astro/src/cli/index.ts, packages/astro/src/cli/help/index.ts, packages/astro/src/cli/add/index.ts, packages/astro/src/cli/check/index.ts, packages/astro/src/cli/dev/index.ts

Development Server Flow

The development server command has the richest visible control flow. Its help output documents foreground server flags such as mode, port, host, browser opening, forced cache clearing, and allowed hosts, and it also documents background-oriented operations. Before starting the normal server path, the command checks whether the invocation is asking for stop, status, or logs, then dynamically imports the matching handler. This keeps background server management under the same astro dev namespace instead of creating separate top-level commands.

Sources: packages/astro/src/cli/dev/index.ts

The foreground path includes two guardrails that are easy to miss from user-facing help alone. First, Astro detects direct agentic environments and turns on JSON logging while allowing background mode to be selected automatically unless the spawned child marker is already present. Second, a lock-file check protects users from accidentally running multiple development servers for the same root. If an existing server is found, the command reports its URL and process identifier and tells the user to stop it or force the new run, which turns a confusing port or process conflict into a concrete recovery step.

Sources: packages/astro/src/cli/dev/index.ts

Add, Check, Version, and Diagnostics

The astro add command is both a package installer workflow and a project configuration workflow. It resolves inline configuration from CLI flags, records a telemetry session for the add command, and prints a detailed help table when invoked without integration names. The source defines aliases such as solid to solid-js and tailwindcss to tailwind, maps official adapter names like Netlify, Vercel, Cloudflare, and Node to packages, and carries stubs for generated configuration files such as Astro config, Tailwind global CSS, Svelte config, Lit npm configuration, and Cloudflare Wrangler configuration.

Sources: packages/astro/src/cli/add/index.ts

The astro check command is deliberately defensive. It ensures the runtime environment is production-like, creates a logger from flags, asks for @astrojs/check and typescript with optional prompt skipping, and stops with a clear error when either dependency is unavailable. Unless disabled by --noSync or bypassed by help, the command runs Astro sync first so generated module types exist before diagnostics are gathered. It then uses @astrojs/check to parse arguments into check configuration and reports the project root being inspected before returning the checker result.

Sources: packages/astro/src/cli/check/index.ts

Version output is provided through a small build-time abstraction rather than by hard-coding a literal value in the command dispatcher. The version provider exposes a version property whose value comes from an environment variable injected during the build. The dispatcher passes that provider to formatting and help infrastructure, so both version display and help rendering can share one source of truth for the package version. This is also why the provider lives under CLI infrastructure: it adapts build metadata into a runtime dependency for command presentation.

Sources: packages/astro/src/cli/infra/build-time-astro-version-provider.ts, packages/astro/src/cli/index.ts

Next Steps

For day-to-day work, begin with astro dev, use astro add when introducing official integrations or adapters, and run astro check when you need diagnostics that include generated Astro types. For command discovery, use the top-level help output first, then command-specific help for flags and subcommands. If your task is creating a new project rather than operating an existing one, continue to the Create Astro CLI page. If your task is moving an existing project across versions, continue to the Upgrade and Migration page. For deployment-oriented command behavior, read the deployment and adapter pages after this reference.