npm package: @mars-stack/cli
Description: MARS CLI: scaffold, configure, and maintain SaaS apps
Latest version: 8.0.17

# @mars-stack/cli

CLI for scaffolding and managing MARS projects. Designed to be used by AI agents (via skills) or directly by developers.

## Install

```bash
# Use without installing (recommended)
npx @mars-stack/cli create my-app

# Or install globally
npm i -g @mars-stack/cli
mars create my-app
```

## Commands

### `mars create [name]`

Scaffold a new project. Walks through four interactive prompt groups:

1. **Project info** -- name (kebab-case), display name, description, URL, support email
2. **Features** -- toggle 24 features across auth, app, infrastructure, and architecture categories
3. **Services** -- pick providers for database, email, storage, payments, analytics, search, realtime, and background jobs
4. **Theme** -- brand colour, font family, design direction

Outputs a complete Next.js application with auth, design tokens, database schema, agent infrastructure (AGENTS.md, skills, rules, docs), and a working dev environment.

**Non-interactive shortcuts**

- `mars create my-app --defaults` — same choices as the default interactive path (minimal feature set, local/console providers).
- `mars create my-app --starter saas` — deterministic **SaaS** preset: enables common product flags (billing, notifications, search, analytics, etc.) with local/`console`/`none` stubs so you are not prompted for every toggle. Use `mars create --help` for the current `--starter` list.

`--defaults` and `--starter` cannot be combined.

```bash
mars create my-app
# → interactive prompts
# → scaffolds ~200 files
# → prints next steps

mars create my-app --starter saas
# → same scaffold path, preset feature + service choices (no feature/theme prompts)
```

### `mars add feature <name>`

Generate a feature module at `src/features/<name>/` with:

- `server/index.ts` -- typed CRUD operations with `import 'server-only'`
- `types.ts` -- Zod validation schemas and TypeScript types

```bash
mars add feature billing
# → src/features/billing/server/index.ts
# → src/features/billing/types.ts
```

### `mars add page <path> [--protected]`

Create a page component with a loading skeleton.

```bash
mars add page pricing                    # → src/app/pricing/page.tsx
mars add page dashboard/analytics -p     # → src/app/(protected)/dashboard/analytics/page.tsx
mars add page blog/[slug]                # → src/app/blog/[slug]/page.tsx
```

### `mars add model <name>`

Create a Prisma schema file with a starter model, timestamps, and user relation.

```bash
mars add model Product
# → prisma/schema/product.prisma (with Product model)
```

### `mars add component <name> [--type primitive|pattern]`

Create a UI component in the correct directory.

```bash
mars add component Toggle                # → src/components/primitives/Toggle.tsx
mars add component DataGrid --type pattern   # → src/components/patterns/DataGrid.tsx
```

### `mars add email <name>`

Create a React Email template with the base layout, inline styles, and email-client-safe markup.

```bash
mars add email team-invite
# → src/lib/core/email/templates/team-invite-email.ts
```

### `mars configure [service]`

Configure a service provider. Installs the SDK, updates `app.config.ts`, and writes env vars to `.env`.

```bash
mars configure payments   # → installs stripe, updates config, adds env vars
mars configure email      # → prompts for SendGrid or Resend, installs SDK
mars configure storage    # → prompts for Vercel Blob, S3, or local
```

### `mars deploy`

Guided Vercel deployment:

1. Checks `vercel` CLI is installed
2. Links the project to your Vercel account
3. Detects configured services from `app.config.ts`
4. Prompts for and sets each required env var
5. Runs the deployment
6. Prints the deployed URL

### `mars doctor [--upgrade-check]`

Check your development environment: Node version, package manager, dependencies, database connection, required env vars.

```bash
mars doctor                 # basic health check
mars doctor --upgrade-check # also check for Mars package updates
```

### `mars upgrade`

Update `@mars-stack/core` and `@mars-stack/ui` to latest, run install, verify with `mars doctor`.

```bash
mars upgrade           # upgrade to latest
mars upgrade --dry-run # preview what would change
```

### `mars template sync`

Copy upstream **template plumbing** (scripts, auth shell files, and other manifest-listed paths) from the CLI-bundled template into an **existing** Mars project. Requires `.mars/scaffold.json` at the project root (from `mars create`); exits with an error if missing.

```bash
mars template sync --dry-run              # list planned changes, no writes
mars template sync                        # default: plumbing category only
mars template sync --only user-owned --force  # overwrite user-owned paths too (backups under .mars/backups/)
```

**vs `mars upgrade`:** `mars upgrade` bumps Mars npm packages only — it does **not** re-copy template source files. Use `mars template sync` when a CLI release includes fixes to `ensure-db.mjs`, proxy, or other synced paths. See the Mars monorepo [scaffold-template-sync-upgrade](https://github.com/greaveselliott/mars/blob/main/docs/exec-plans/active/scaffold-template-sync-upgrade.md) exec plan for the safety model and path inventory.

### `mars telemetry <enable|disable>`

Opt in or out of anonymous usage analytics. Stored in `~/.marsrc`. Tracks command usage and feature selections only -- never project names, file contents, or env vars.

## Agent Usage

The CLI is designed to be invoked by AI agents following Mars skills. The agent reads the skill, determines which CLI commands to run, and executes them. For example:

- The `build-complete-feature` meta-skill chains `mars add model`, `mars add feature`, and `mars add page`
- The `setup-billing` meta-skill runs `mars configure payments` then builds the billing UI
- The `deploy-to-vercel` skill runs `mars deploy` with guided prompts

Skills live in `.cursor/skills/` (installed automatically via `@mars-stack/core` postinstall).

## License

MIT