> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# create-mastra

创建独立的 Mastra 项目。默认情况下，`create-mastra` 会安装默认 starter，并针对你选择的模型 Provider 进行配置。

**npm**:

```bash
npx create-mastra@latest
```

**pnpm**:

```bash
pnpm dlx create-mastra@latest
```

**Yarn**:

```bash
yarn dlx create-mastra@latest
```

**Bun**:

```bash
bun x create-mastra@latest
```

## 创建模式

### 默认 starter

默认 starter 会创建一个 Agent harness，其中包含 Workspace Tool、Memory、任务跟踪、Web 访问、定期调度、Storage 和 Observability。可以选择 OpenAI、Anthropic、Gemini 或 xAI 作为模型 Provider。

同时提供项目名称和 Provider，即可在不显示提示的情况下创建项目。以下示例使用 Anthropic；你也可以传入 `openai`、`google` 或 `xai`：

**npm**:

```bash
npx create-mastra@latest my-mastra-project --llm anthropic
```

**pnpm**:

```bash
pnpm dlx create-mastra@latest my-mastra-project --llm anthropic
```

**Yarn**:

```bash
yarn dlx create-mastra@latest my-mastra-project --llm anthropic
```

**Bun**:

```bash
bun x create-mastra@latest my-mastra-project --llm anthropic
```

省略 `--llm` 可通过交互方式选择 Provider，并可选择输入其 API key。交互式设置还会询问是否将项目连接到 Mastra 平台。启用后，该命令会打开浏览器身份验证流程，并创建一个与本地项目同名的平台项目。随后，它会将 `MASTRA_PLATFORM_ACCESS_TOKEN` 和 `MASTRA_PROJECT_ID` 写入 `.env`。

### 模板

使用模板 slug 或公开的 GitHub URL：

**npm**:

```bash
npx create-mastra@latest my-mastra-project --template agent-harness
```

**pnpm**:

```bash
pnpm dlx create-mastra@latest my-mastra-project --template agent-harness
```

**Yarn**:

```bash
yarn dlx create-mastra@latest my-mastra-project --template agent-harness
```

**Bun**:

```bash
bun x create-mastra@latest my-mastra-project --template agent-harness
```

**npm**:

```bash
npx create-mastra@latest my-mastra-project --template https://github.com/mastra-ai/template-agent-harness
```

**pnpm**:

```bash
pnpm dlx create-mastra@latest my-mastra-project --template https://github.com/mastra-ai/template-agent-harness
```

**Yarn**:

```bash
yarn dlx create-mastra@latest my-mastra-project --template https://github.com/mastra-ai/template-agent-harness
```

**Bun**:

```bash
bun x create-mastra@latest my-mastra-project --template https://github.com/mastra-ai/template-agent-harness
```

将模板值留空可通过交互方式选择模板：

**npm**:

```bash
npx create-mastra@latest my-mastra-project --template
```

**pnpm**:

```bash
pnpm dlx create-mastra@latest my-mastra-project --template
```

**Yarn**:

```bash
yarn dlx create-mastra@latest my-mastra-project --template
```

**Bun**:

```bash
bun x create-mastra@latest my-mastra-project --template
```

模板作者负责其依赖项、模型、环境变量和源代码。`create-mastra` 不会应用 `--llm` 或 `--llm-api-key`。

### 空 scaffold

使用 `--empty` 创建一个不含 Provider、Agent、示例、模型 SDK 或环境文件的项目：

**npm**:

```bash
npx create-mastra@latest my-empty-project --empty
```

**pnpm**:

```bash
pnpm dlx create-mastra@latest my-empty-project --empty
```

**Yarn**:

```bash
yarn dlx create-mastra@latest my-empty-project --empty
```

**Bun**:

```bash
bun x create-mastra@latest my-empty-project --empty
```

## 自动设置

安装依赖项后，该命令会：

1. 检测 `PATH` 中受支持的编程助手并安装 Mastra Skill。如果未检测到，则安装通用 Skill。
2. 当当前目录和生成的项目尚未位于 Git 仓库中时，创建初始 Git commit。

使用 `--no-skills` 或 `--no-git` 可跳过这些步骤。Skill 和 Git 设置失败会产生警告，但不会移除已成功创建的项目。

## 冲突与验证

- `--empty` 和 `--template` 不能同时使用。
- `--llm` 和 `--llm-api-key` 仅适用于默认 starter 项目。
- 项目名称必须是安全的、小写的单一目录名称，且目标不能已存在。

系统会在获取模板或创建文件之前拒绝无效输入。

## 参数和 flag

**\[project-name]** (`string`): 项目目录和 package 名称。省略时，该命令会提示输入。

**--empty** (`boolean`): 创建一个最小化且不含 Provider 的 Mastra 项目。

**-l, --llm \<provider>** (`string`): 托管的 Agent harness Provider：openai、anthropic、google 或 xai。

**-k, --llm-api-key \<key>** (`string`): 自动设置 Provider 成功后，将所选 Provider 的 API key 写入生成的 .env 文件。

**--no-skills** (`boolean`): 跳过自动安装 Mastra Skill。

**--no-git** (`boolean`): 跳过自动初始化 Git 和创建初始 commit。

**--no-install** (`boolean`): 跳过依赖项安装。

**-t, --template \[template]** (`string`): 使用模板 slug 或公开的 GitHub URL。省略该值可通过交互方式选择。

**--timeout \<milliseconds>** (`number`): 安装依赖项的正整数超时时间。默认为 60000。

**--version** (`boolean`): 输出 create-mastra 版本。

**--help** (`boolean`): 显示命令帮助。

## 遥测

Mastra 会收集匿名的 CLI 使用信息，例如操作系统、Mastra 版本和 Node.js 版本。你可以查看[分析功能源代码](https://github.com/mastra-ai/mastra/blob/main/packages/cli/src/analytics/index.ts)。

设置 `MASTRA_TELEMETRY_DISABLED=1` 可选择退出：

```bash
MASTRA_TELEMETRY_DISABLED=1 npx create-mastra@latest my-project --empty
```