---
title: "Scaffold Your Project"
description: "Create a new MastraKit project with the CLI"
source: /docs/scaffold
---


Create Your Project [#create-your-project]

Run the scaffold command with your [license key](/docs/license):

```bash
npx mastrakit my-project --key sk_live_your_key_here
```

Or set the key as an environment variable first:

```bash
export MASTRAKIT_LICENSE_KEY=sk_live_your_key_here
npx mastrakit my-project
```

The CLI will prompt you for:

| Prompt                      | Options                    | Default     |
| --------------------------- | -------------------------- | ----------- |
| **Auth provider**           | Better Auth                | Better Auth |
| **Payments**                | Stripe, Polar              | Stripe      |
| **Include metering**        | Yes / No                   | No          |
| **Include docs site**       | Yes / No                   | No          |
| **LLM provider**            | Anthropic, OpenAI          | Anthropic   |
| **Currency**                | EUR, USD                   | EUR         |
| **Version control & CI/CD** | GitHub (recommended), None | GitHub      |

CLI Flags [#cli-flags]

```bash
npx mastrakit [project-name] [flags]
```

| Flag                      | Description                                            |
| ------------------------- | ------------------------------------------------------ |
| `--key <license-key>`     | License key (or set `MASTRAKIT_LICENSE_KEY` env var)   |
| `--owner <owner>`         | GitHub user or org to create the repo under            |
| `--deploy`                | Run the deploy wizard after scaffolding                |
| `--skip-install`          | Skip `pnpm install`                                    |
| `--no-github`             | Skip GitHub repo creation                              |
| `--no-cache`              | Force fresh template download                          |
| `--yes`                   | Accept all defaults (non-interactive)                  |
| `--dry-run`               | Preview what would be scaffolded without writing files |
| `--local-template <path>` | Use a local template directory (dev mode)              |

What Gets Created [#what-gets-created]

```
my-project/
├── apps/
│   ├── web/          # TanStack Start frontend
│   ├── api/          # Hono REST API
│   ├── auth/         # Better Auth service
│   ├── mastra/       # AI agent + MCP server
│   └── metering/     # Credit ledger (if selected)
├── packages/
│   └── shared/       # Types, schemas, plans, i18n
├── scripts/
│   ├── conductor/    # Workspace automation (if GitHub selected)
│   ├── env/          # Environment secret management
│   └── dev/          # Local development helpers
├── .github/
│   └── workflows/    # CI/CD pipelines (if GitHub selected)
└── .mastrakit/
    └── config.json   # Your scaffold selections
```

GitHub Setup (if selected) [#github-setup-if-selected]

When you choose GitHub as your CI/CD option, the scaffold:

1. Runs `git init` and creates an initial commit
2. Prompts for the GitHub **owner** (your user or one of your orgs)
3. Creates a **private** GitHub repository via `gh repo create <owner>/<name> --private`
4. Pushes the initial commit

Repos are always created private. Change visibility afterwards with `gh repo edit <owner>/<name> --visibility public`.

The `gh` CLI must be installed and authenticated (`gh auth login`). If it's not available, the scaffold will warn you and fall back to "None".

Choosing an Organization [#choosing-an-organization]

If your authenticated `gh` user belongs to any organizations, the CLI prompts:

```
? Create GitHub repository under:
❯ jan-doe (personal)
  themakers-labs
  my-other-org
```

Organizations are discovered via `gh api user/orgs`. To create under an org non-interactively, pass `--owner`:

```bash
npx mastrakit my-project --owner themakers-labs
```

If your `gh` user has no organizations, the scaffold skips the prompt and uses your personal account.

Non-Interactive Mode [#non-interactive-mode]

Skip all prompts with `--yes` to accept defaults. Combine with `--owner` to pin the GitHub target:

```bash
npx mastrakit my-project \
  --yes \
  --key sk_live_your_key_here \
  --owner themakers-labs
```

Skip dependency installation:

```bash
npx mastrakit my-project --skip-install
```

Preview without writing files:

```bash
npx mastrakit my-project --dry-run
```

Configuration File [#configuration-file]

After scaffolding, your selections are saved to `.mastrakit/config.json` in the project root:

```json
{
  "version": "0.1.14",
  "createdAt": "2026-04-21T12:00:00.000Z",
  "components": {
    "auth": "better-auth",
    "llm": "anthropic",
    "payments": "stripe",
    "currency": "eur",
    "metering": false,
    "docs": false,
    "cicd": "github"
  }
}
```

This file is used by the deploy wizard (`npx mastrakit deploy`) to know which services to provision and configure. Don't delete it.

After Scaffolding [#after-scaffolding]

```bash
cd my-project
pnpm install        # Install dependencies (if --skip-install was used)
pnpm dev            # Start all services locally
```

When ready to deploy, run the deploy wizard:

```bash
npx mastrakit deploy
```

Or use a deploy config file for non-interactive deployment:

```bash
npx mastrakit deploy --config deploy.json
```