@mars-stack/cli

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

Install

# 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.

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

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.

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.

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.

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.

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.

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.

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. Does not bump @mars-stack/cli itself or copy template source files — use mars template sync for template plumbing updates.

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.

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 exec plan for the safety model and path inventory.

mars telemetry <enable|disable|status>

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.

• enable — opt in to anonymous telemetry
• disable — opt out
• status — show whether telemetry is currently enabled or disabled

Actions are case-insensitive. An unrecognised action exits non-zero with a descriptive error.

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