Skip to content
xtarter
Blog

CLI Reference

Command

Section titled “Command”
npx create-xtarter-app@latest [project-name] [options]

Arguments

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

Options

Section titled “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

Section titled “Subcommands”
Command Description
preview [template] Preview template details without scaffolding

Package managers

Section titled “Package managers”
Manager Command Note
pnpm (default) Fast, disk-efficient
npm - Default Node.js
bun - Ultra-fast runtime
yarn - Classic choice

Examples

Section titled “Examples”
Interactive
npm create xtarter-app@latest
Quick start with defaults
npm create xtarter-app@latest -- my-app --yes
Scaffold in current directory
npm create xtarter-app@latest -- . -t vite-tailwind
Pick a template
npm create xtarter-app@latest -- my-app --template vite-tailwind
Specific package manager, no git
npm create xtarter-app@latest -- my-app --pm bun --no-git
Overwrite existing directory
npm create xtarter-app@latest -- my-app -t vite-tailwind --force
Download a specific tag
npm create xtarter-app@latest -- my-app --ref v1.0.0
Preview a template
npm create xtarter-app@latest -- preview next-tailwind

Error handling

Section titled “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

Section titled “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.