# 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](/create-xtarter-app/guide/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

```bash
  # 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
  ```

  ```bash
  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
  ```

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

  ```bash
  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:

```ts
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](/create-xtarter-app/guide/templates/) for the full `TemplateConfig` type.