CLI Reference

Command

npx create-xtarter-app@latest [project-name] [options]

Arguments

Argument	Required	Description
project-name	No	Name for the new project. If omitted, you’ll be prompted.

Options

Option	Alias	Type	Default	Description
--template	-t	string	—	Template ID to use (skips prompt). See Templates
--pm	-p	string	—	Package manager (pnpm, npm, bun, yarn)
--no-git	—	boolean	—	Skip git initialization
--clean	—	boolean	—	Remove CI/CD config files after scaffolding
--force	-f	boolean	—	Overwrite existing target directory
--ref	—	string	—	Git ref (branch, tag, or commit SHA) to download
--yes	-y	boolean	—	Use defaults for all prompts
--help	-h	boolean	—	Show help text
--version	-v	boolean	—	Show version

Subcommands

Command	Description
preview [template]	Preview template details without scaffolding

Package managers

Manager	Command	Note
pnpm	(default)	Fast, disk-efficient
npm	—	Default Node.js
bun	—	Ultra-fast runtime
yarn	—	Classic choice

Examples

pnpm

# Interactive — prompts for everything
pnpm create xtarter-app

# Quick start with defaults
pnpm create xtarter-app my-app --yes

# Scaffold in current directory
pnpm create xtarter-app . -t vite-tailwind

# Pick a template
pnpm create xtarter-app my-app --template vite-tailwind

# Specific package manager, no git
pnpm create xtarter-app my-app --pm bun --no-git

# Overwrite existing directory
pnpm create xtarter-app my-app -t vite-tailwind --force

# Download a specific tag
pnpm create xtarter-app my-app --ref v1.0.0

# Preview a template
pnpm create xtarter-app preview next-tailwind

npm

npm create xtarter-app@latest
npm create xtarter-app@latest my-app --yes
npm create xtarter-app@latest my-app --template vite-tailwind
npm create xtarter-app@latest my-app --template vite-tailwind --force

bun

bun create xtarter-app
bun create xtarter-app my-app --yes
bun create xtarter-app my-app --template vite-tailwind

yarn

yarn create xtarter-app
yarn create xtarter-app my-app --yes
yarn create xtarter-app my-app --template vite-tailwind

Error handling

• Invalid template ID — prints all valid template IDs and exits
• Invalid package manager — prints valid options and exits
• Target directory exists — cancels with an error unless --force is used
• Invalid project name — validation fails during prompt
• Download failure — retries up to 3 times, then exits with error
• Install failure — cleans up created directory (if scaffolded to a new path), then exits
• Partial scaffold — if any step after download fails, created directories are cleaned up automatically

Programmatic API

The package also exports a programmatic API for use in scripts and tooling:

import {
  downloadTemplateFiles,
  modifyPackageJson,
  installDependencies,
  initializeGit,
  isGitInstalled,
  cleanCIConfigs,
  getTemplateById,
  getTemplateChoices,
  TEMPLATES,
} from 'create-xtarter-app'

// Download a template
await downloadTemplateFiles({
  template: getTemplateById('vite-tailwind')!,
  targetPath: './my-app',
})

// Modify package.json
await modifyPackageJson({ projectPath: './my-app', projectName: 'my-app' })

// Install dependencies
await installDependencies({ packageManager: 'pnpm', projectPath: './my-app' })

// Initialize git
if (isGitInstalled()) {
  await initializeGit({ projectPath: './my-app' })
}

See Templates for the full TemplateConfig type.