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 (defaults to next-chakra template when -t is omitted)
--quiet	-	boolean	-	Suppress banners, spinners, and decorative output
--json	-	boolean	-	Output scaffold result as JSON (also suppresses banners and spinners)
--no-color	-	boolean	-	Disable colorized output
--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

JSON output

# Scaffold and get machine-readable result
pnpm create xtarter-app my-app --yes --json

Output:

{
  "success": true,
  "projectPath": "./my-app",
  "template": "next-chakra",
  "packageManager": "pnpm",
  "gitInitialized": true,
  "dependenciesInstalled": true,
  "ciConfigsCleaned": false,
  "nextSteps": [
    "cd my-app",
    "pnpm dev"
  ]
}

On failure, the output is written to stderr:

{ "success": false, "error": "message" }

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.