Create Astro CLI

Purpose and Scope

create-astro is Astro’s project scaffolding command. Use it when you want a new Astro project directory created from a starter template, with the common setup decisions handled by prompts or command-line flags. The package README describes it as “Scaffolding for Astro projects” and shows it as the recommended entry point for starting with npm, Yarn, or pnpm. That makes this CLI different from the astro project CLI used after a project already exists: create-astro gets the project onto disk, then the installed Astro project can use commands such as development, build, and preview.

Sources: packages/create-astro/README.md, packages/create-astro/package.json

The package is published as create-astro, versioned independently inside the Astro monorepo, and exposes a create-astro binary. Its package metadata points both exports and main at ./create-astro.mjs, so consumers run the bundled command rather than importing source TypeScript directly. The package requires Node >=22.12.0, depends on @astrojs/cli-kit and @bluwy/giget-core, and uses bundled development dependencies such as arg and astro-scripts. Those details matter for maintainers: user-facing behavior is designed in src/index.ts, but distribution is through the generated executable entrypoint declared in package.json.

Sources: packages/create-astro/package.json, packages/create-astro/src/index.ts

Relevant Source Files

• packages/create-astro/README.md — User-facing command examples for npm, Yarn, and pnpm; project-name and template arguments; GitHub template support; and the supported CLI flags.
• packages/create-astro/package.json — Package identity, binary/export entrypoints, Node engine requirement, build/test scripts, publish metadata, and bundled/runtime dependency boundaries.
• packages/create-astro/src/index.ts — Runtime orchestration for the CLI: argument cleanup, context creation, help handling, ordered setup actions, task execution, next steps, signal handling, and public testable exports.

Command Forms and Package Managers

The most direct command is npm create astro@latest. The README also documents yarn create astro and pnpm create astro, matching the package-manager conventions for invoking a package named create-astro. In interactive mode, the CLI asks for the information it needs, so the command can be short when you are starting manually. This is the path to recommend for new users because it lets the scaffolder guide them through naming the project, choosing a template, deciding whether to install dependencies, and deciding whether to initialize Git.

# npm
npm create astro@latest
 
# Yarn
yarn create astro
 
# pnpm
pnpm create astro

For repeatable setup, documentation, workshops, and automation, the README shows positional and flag-based forms that provide the project name and template up front. npm uses an extra -- separator before flags in the documented example, while Yarn and pnpm pass --template directly. The implementation intentionally filters a standalone -- out of process.argv.slice(2) before creating the CLI context. A source comment explains that this protects the argument parser across npm behavior changes where the separator may be forwarded to the command. In practice, users can follow the package-manager examples without needing to understand that compatibility detail.

Sources: packages/create-astro/README.md, packages/create-astro/src/index.ts

# npm
npm create astro@latest my-astro-project -- --template minimal
 
# yarn
yarn create astro my-astro-project --template minimal
 
# pnpm
pnpm create astro my-astro-project --template minimal

Templates and Project Arguments

A template is the starter project copied into the new directory. The README uses minimal as the compact example and links to the monorepo examples directory as the full list of example templates. You can also use a GitHub repository as the template source, such as cassidoo/shopify-react-astro. This gives create-astro two useful modes: a curated starter mode for common Astro project shapes, and a repository-template mode for teams that maintain their own baseline. The public contract is the same in both cases: provide a target project directory, provide or choose a template, and let the CLI perform the setup steps.

Sources: packages/create-astro/README.md

npm create astro@latest my-astro-project -- --template cassidoo/shopify-react-astro

When documenting or scripting a starter workflow, treat the project name as the destination path and --template as the source selection. If neither is supplied, the interactive flow can ask for them. If both are supplied, the CLI can move through the setup with fewer prompts, especially when combined with --yes or --no. The README’s wording says flags may be provided in place of prompts, which is the key rule: the same scaffolding decisions exist whether they are answered interactively or declared on the command line.

CLI Flags Reference

The README lists the supported flags for replacing prompts or changing execution behavior. --help and -h display available flags without scaffolding a project. --template <name> selects the starter template. --install and --no-install control dependency installation, while --git and --no-git control repository initialization. --add <integrations> asks the scaffolder to add Astro integrations during creation. --no-ai skips AI agent files, which is useful for teams that do not want generated assistant-oriented project files in a starter. --yes or -y accepts defaults; --no or -n declines defaults.

Sources: packages/create-astro/README.md

--dry-run is especially useful when writing docs or testing a command line because it lets users walk through the decisions without changing the filesystem. --ref is a maintainer-oriented escape hatch for choosing an Astro branch instead of the default latest release. --fancy exists for Windows terminal rendering differences; it is not a project feature, but a presentation option. Keep these flags in the scaffolding phase of your mental model: after a project is created, day-to-day development moves to the Astro project and its own scripts.

Execution Flow

The TypeScript entrypoint makes the scaffolding lifecycle explicit. It registers SIGINT and SIGTERM handlers that exit cleanly, prints an initial blank line to create separation from package-manager output, normalizes arguments, and calls getContext(cleanArgv). The context is the shared state object that later actions read and update. If that context indicates help was requested, help() runs and main() returns before project setup begins. This early help branch is why --help behaves like a reference command rather than a partial project creation.

Sources: packages/create-astro/src/index.ts

After context creation, main() runs a fixed sequence of actions: verify, intro, projectName, template, dependencies, and git. The inline comment notes that steps which write files need to run before Git, so Git initialization can capture the generated project state. Once the actions have prepared tasks on the context, the command calls tasks() from @astrojs/cli-kit with labels for “Project initializing...” and “Project initialized!” and the accumulated ctx.tasks. Finally, it calls next(ctx) to print follow-up instructions and exits with status zero.

Sources: packages/create-astro/src/index.ts

This action-based shape is important for contributors because each phase has a narrow responsibility. projectName determines where the project should go, template handles starter processing, dependencies prepares installation work, and git handles repository setup. The entrypoint also re-exports the action functions, getContext, setStdout, and template helpers such as generateAgentsMd, processTemplateReadme, and removeTemplateMarkerSections. Those exports give tests and internal callers stable access to the building blocks without requiring the full interactive command to run.

Sources: packages/create-astro/src/index.ts

Development and Maintenance Notes

For maintainers working in the monorepo, packages/create-astro/package.json defines the local lifecycle. pnpm --filter create-astro build maps to astro-scripts build "src/index.ts" --bundle && tsc -b, while build:ci performs the bundled build without the TypeScript build step shown in the regular script. dev watches src/**/*.ts, and test targets test/**/*.test.ts through astro-scripts test. These scripts explain how source TypeScript becomes the published command and how changes to prompts, flags, and orchestration should be validated.

Sources: packages/create-astro/package.json

When adding or changing a flag, update the reader-facing README, the argument/context handling behind getContext, and any action that consumes the resulting context value. When changing setup order, preserve the constraint documented in src/index.ts: file-writing steps should stay before Git initialization. When changing distribution behavior, verify the bin, exports, main, files, and Node engine fields still describe the generated package accurately. A good next step after reading this page is to compare this scaffolding CLI with the project-level astro CLI reference, because users encounter create-astro first and then switch to commands inside the generated project.