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

# CLI 命令

你可以使用 Mastra 提供的命令行界面（CLI）来开发、构建和启动 Mastra 项目。

## `mastra dev`

启动一个服务器，为 Agent、Tool 和 Workflow 提供 [Studio](https://mastra.zisheng.pro/docs/studio/overview) 与 REST endpoint。`mastra dev` 运行后，你可以访问 <http://localhost:4111/swagger-ui> 查看所有可用 endpoint。

你也可以[配置服务器](https://mastra.zisheng.pro/reference/configuration)。

### Flag

该命令接受[通用 flag](#common-flags) 以及以下额外 flag：

#### `--https`

启用本地 HTTPS 支持。[了解详情](https://mastra.zisheng.pro/reference/configuration)。

#### `--inspect`

以 inspect 模式启动开发服务器，便于调试。你也可以指定自定义 host 和 port（例如 Docker 可使用 `--inspect=0.0.0.0:9229`）。此 flag 不能与 `--inspect-brk` 同时使用。

#### `--inspect-brk`

以 inspect 模式启动开发服务器，并在脚本开头暂停。你也可以指定自定义 host 和 port（例如 `--inspect-brk=0.0.0.0:9229`）。此 flag 不能与 `--inspect` 同时使用。

#### `--custom-args`

传给 Node.js 进程的自定义参数列表，以逗号分隔，例如 `--require=newrelic` 或 `--experimental-transform-types`。

#### `--request-context-presets`

包含[请求上下文](https://mastra.zisheng.pro/docs/server/request-context)预设的 JSON 文件路径。提供后，Studio 的请求上下文编辑器中会显示下拉菜单，让你可以在预设配置之间快速切换。

```bash
mastra dev --request-context-presets ./presets.json
```

该文件必须是 JSON 对象，其中每个 key 是预设名称，每个 value 是一个对象：

```json
{
  "development": { "userId": "dev-user", "env": "development" },
  "production": { "userId": "prod-user", "env": "production" }
}
```

### 配置

你可以设置环境变量来调整 `mastra dev` 的行为。

#### 跳过 peer dependency 检查

设置 `MASTRA_SKIP_PEERDEP_CHECK=1`，可在启动时跳过 peer dependency 版本不匹配检查：

```bash
MASTRA_SKIP_PEERDEP_CHECK=1 mastra dev
```

这在 monorepo 开发期间很有用，因为 peer dependency 可能已经升级，但 package 尚未发布。

#### 禁用构建缓存

设置 `MASTRA_DEV_NO_CACHE=1`，可强制执行完整的重新构建，而不使用 `.mastra/` 下的缓存资源：

```bash
MASTRA_DEV_NO_CACHE=1 mastra dev
```

当你调试 bundler plugin 或怀疑输出已过期时，这会很有帮助。

#### 限制并行度

`MASTRA_CONCURRENCY` 用于限制并行运行的高开销操作数量（主要是构建和评估步骤）。例如：

```bash
MASTRA_CONCURRENCY=4 mastra dev
```

不设置该变量时，CLI 会根据当前机器选择合理的默认值。

#### 自定义 Provider endpoint

使用 Vercel AI SDK 支持的 Provider 时，可以设置 base URL，通过代理或内部 gateway 重定向请求。以 OpenAI 为例：

```bash
OPENAI_API_KEY=<your-api-key> \
OPENAI_BASE_URL=https://openrouter.example/v1 \
mastra dev
```

以 Anthropic 为例：

```bash
ANTHROPIC_API_KEY=<your-api-key> \
ANTHROPIC_BASE_URL=https://anthropic.internal \
mastra dev
```

这些变量会转发给 Mastra model router，并适用于任何选择的 `"openai/..."` 或 `"anthropic/..."` 模型。

## `mastra factory dev`

启动用于开发 [Agent Builder](https://agent-builder.mastra.ai/) 的开发服务器。它与 [`mastra dev`](#mastra-dev) 使用相同的开发 runtime 和 flag，并写入同一个 `.mastra/output` 目录。

```bash
npx mastra factory dev
```

两个命令共用同一个开发锁，因此 `mastra dev` 和 `mastra factory dev` 无法在同一项目中同时运行。如果其中一个已在运行，另一个会退出并报告开发服务器重复错误。

开发 Agent Builder 功能时，请使用 `mastra factory dev`。它接受与 [`mastra dev`](#mastra-dev) 相同的 flag，包括 `--https`、`--inspect`、`--inspect-brk`、`--custom-args` 和 `--request-context-presets`。

## `mastra build`

`mastra build` 命令会将 Mastra 项目打包为可用于生产环境的 Hono 服务器。[Hono](https://hono.dev/) 是一个轻量且类型安全的 Web framework，借助其中间件支持，可以轻松将 Mastra Agent 部署为 HTTP endpoint。

在底层，Mastra 的 Rollup 服务器会找到 Mastra 入口文件，并将其打包为可用于生产环境的 Hono 服务器。打包期间，它会对代码执行 tree-shaking，并生成用于调试的 source map。

可以使用 [`mastra start`](#mastra-start) 将 `.mastra` 中的输出部署到任何云服务器。

如果要部署到[无服务器平台](https://mastra.zisheng.pro/docs/deployment/cloud-providers)，则需要安装正确的 deployer，才能在 `.mastra` 中获得正确的输出。

该命令接受[通用 flag](#common-flags)。

### Flag

#### `--studio`

将 Studio UI 打包到构建产物中。

### 配置

你可以设置环境变量来调整 `mastra build` 的行为。

#### 跳过 peer dependency 检查

设置 `MASTRA_SKIP_PEERDEP_CHECK=1`，可跳过 peer dependency 版本不匹配检查：

```bash
MASTRA_SKIP_PEERDEP_CHECK=1 mastra build
```

#### 限制并行度

在 CI 或资源受限的环境中，可以设置 `MASTRA_CONCURRENCY` 来限制同时运行的高开销任务数量。

```bash
MASTRA_CONCURRENCY=2 mastra build
```

## `mastra start`

> **信息:** 使用 `mastra start` 前，需要先运行 `mastra build`。

启动本地服务器，以生产模式运行已构建的 Mastra 应用。默认启用 [OTEL Tracing](https://mastra.zisheng.pro/docs/observability/tracing/overview)。

### Flag

该命令接受[通用 flag](#common-flags) 以及以下额外 flag：

#### `--dir`

已构建的 Mastra 输出目录路径。默认为 `.mastra/output`。

#### `--custom-args`

传给 Node.js 进程的自定义参数列表，以逗号分隔，例如 `--require=newrelic` 或 `--experimental-transform-types`。

## `mastra worker build`

打包 Mastra 应用以部署 worker。生成的输出与 `mastra build` 相同：一个自包含的 `.mastra/output/` 目录。

```bash
mastra worker build [options]
```

### Flag

#### `--dir`

Mastra 源目录路径。默认为 `src/mastra`。

#### `--root`

项目根目录。默认为当前目录。

#### `--tools`

要包含在 bundle 中的 Tool 路径，以逗号分隔。

#### `--output-dir`

自定义输出目录。默认为 `.mastra/output`。

#### `--debug`

在构建期间启用 debug 日志。

## `mastra experiment build`

构建一个独立的配套 worker，用于运行实验，但不公开 HTTP 服务器。该 worker 会加载导出的 `Mastra` 实例，并通过标准输入接收带版本的换行符分隔 JSON（NDJSON）协议消息，再将协议事件写入标准输出。

```bash
mastra experiment build [options]
```

默认情况下，该命令会将 worker 写入 `.mastra/experiment-worker`。此目录包含可执行入口点、生产依赖项和 `experiment-worker-manifest.json`。标准输出应仅用于协议输出。Worker 诊断信息会写入标准错误。

### Artifact 约定

`experiment-worker-manifest.json` 将该 artifact 标识为版本 `1` 的 `mastra-experiment-worker`，并提供：

- 嵌入可执行文件中的 CLI 版本、创建时间和唯一 build ID。
- 支持的协议版本和数据集规范化版本。
- 启动 worker 所需的可执行文件、参数和工作目录。
- 依赖项 manifest 和生成的 lockfile 路径。
- 每个 artifact 文件排序后的 SHA-256 digest。
- 根据这些文件路径和 digest 派生的 SHA-256 内容 digest。

内容 digest 不包含 `experiment-worker-manifest.json`，以避免自引用 digest。请将 manifest 与目录中的其余内容一起打包。如果必须证明 manifest 本身，请使用外层 package digest。

### 协议约定

该 worker 实现固定为版本 `1` 的实验配套 worker 协议。它从标准输入读取严格的 UTF-8 NDJSON frame，并要求每个 frame（包括最后一个）都以换行符结尾。大于 1 MiB 的 frame、格式错误或被截断的 frame、不受支持的协议或规范化版本，以及与当前实验 correlation 不匹配的消息，都会被视为协议失败而拒绝。

运行请求必须与 artifact 中嵌入的 build ID 一致，并包含有序数据集条目数和 SHA-256 attestation。Worker 会发出从 `0` 开始的连续序号、由 timer 驱动的 heartbeat、已等待完成的实验生命周期事件，以及恰好一个终止事件。取消请求必须与当前协议版本、experiment ID、job ID、attempt 和 idempotency key 一致。

协议退出码如下：

| 代码   | 含义          |
| ---- | ----------- |
| `0`  | 已完成         |
| `10` | 已完成，但存在条目错误 |
| `20` | 致命失败        |
| `21` | 可重试失败       |
| `30` | 已取消         |
| `31` | 已超时         |
| `70` | 协议失败        |

### Packet 字段处理

Worker 会将目标标识、有序的内联数据集条目、Scorer ID、并发数、超时时间、实验 metadata、请求上下文、Tool mock 和取消信息传给 `runExperiment`。Scorer 版本和 artifact provenance 会保留为实验 metadata。Scorer 代码 provenance 由 artifact admission 强制执行，而不是在 runtime 查找 Scorer。

版本 `1` 会以确定性方式拒绝未声明的 Tool。非空 network allowlist 和 secret reference 会因 policy 失败而被拒绝，因为网络强制规则和 secret materialization 属于进程 sandbox 的职责。数据集条目的来源和 expected-trajectory 字段会在传给 `runExperiment` 时保留为条目 metadata。

### Flag

#### `--dir`

Mastra 源目录路径。默认为 `src/mastra`。

#### `--root`

项目根目录。默认为当前目录。

#### `--output-dir`

自定义 artifact 目录。相对路径从项目根目录解析。默认为 `.mastra/experiment-worker`。

#### `--debug`

在构建期间启用 debug 日志。

## `mastra worker start`

> **信息:** 使用 `mastra worker start` 前，需要先运行 `mastra worker build` 或 `mastra build`。

从之前构建的 bundle 启动 worker 进程。可选的 `name` 参数会在生成的进程中设置 `MASTRA_WORKERS`，控制要启动哪个 worker。

```bash
mastra worker start [name] [options]
```

### Flag

#### `--dir`

构建输出目录的路径。默认为 `.mastra/output`。

#### `--env`

环境文件的路径。默认为 `.env.production`，找不到时回退到 `.env`。

### 示例

```bash
# Start only the orchestration worker
mastra worker start orchestration

# Start only the scheduler
mastra worker start scheduler

# Start from a custom build directory
mastra worker start orchestration --dir ./dist
```

有关部署拓扑和配置，请参阅 [Worker](https://mastra.zisheng.pro/docs/deployment/workers)。

## `mastra studio`

以静态服务器形式启动 [Studio](https://mastra.zisheng.pro/docs/studio/overview)。启动后，你可以输入 Mastra 实例 URL（例如 `http://localhost:4111`），将 Studio 连接到 Mastra backend。该命令会在当前工作目录中查找 `.env` 和 `.env.production` 文件以获取配置。

### Flag

该命令接受[通用 flag](#common-flags) 以及以下额外 flag：

#### `--port`

运行 Studio 的 port。默认为 `3000`。

#### `--server-host`

要连接的 Mastra API 服务器 host。默认为 `localhost`。

#### `--server-port`

要连接的 Mastra API 服务器 port。默认为 `4111`。

#### `--server-protocol`

要连接的 Mastra API 服务器协议。默认为 `http`。

#### `--server-api-prefix`

Mastra API 服务器的 API route prefix。默认为 `/api`。

#### `--request-context-presets`

包含[请求上下文](https://mastra.zisheng.pro/docs/server/request-context)预设的 JSON 文件路径。其工作方式与 [`mastra dev` flag](#--request-context-presets) 相同。

```bash
mastra studio --request-context-presets ./presets.json
```

## `mastra deploy`

构建项目，并将其部署到 `--env` 选择的 Mastra 平台环境。这是所有新部署的推荐命令，它取代了 [`mastra studio deploy`](#mastra-studio-deploy) 和 [`mastra server deploy`](#mastra-server-deploy)。后两者仍可使用，但不应再用于新设置。

该命令需要通过 [`mastra auth login`](#mastra-auth-login) 或 `MASTRA_API_TOKEN` 环境变量进行身份验证。

```bash
mastra deploy
mastra deploy --env staging
mastra deploy --env production --region eu
```

该命令先运行 `mastra build` 并压缩输出，再将其上传到所选环境。随后，它会轮询部署状态并流式输出构建日志，直到部署进入终止状态。

组织、项目和环境按以下顺序解析：环境变量（`MASTRA_ORG_ID`、`MASTRA_PROJECT_ID`）、CLI flag（`--org`、`--project`、`--env`）、`.mastra-project.json` 配置文件、凭据中的当前组织，最后是交互式提示。首次部署时，CLI 会将解析出的组织和项目 ID 保存到 `.mastra-project.json`，后续部署便会跳过提示。

如果项目尚不存在，CLI 会在确认后使用 `package.json` 的 `name` 字段创建项目。如果目标环境不存在，CLI 会在确认后创建该环境（除 `production` 外，默认使用 `type: staging`）。与 `--yes` 结合使用时，可通过一条非交互式命令创建并部署所有内容：

```bash
mastra deploy --env staging --yes
```

设置 `--env <name>` 且未设置 `--env-file` 时，如果项目目录中存在 `.env.<name>`（例如 `.env.staging`），CLI 会自动选择该文件。将 `<name>` 插入文件路径前，会使用严格的 allowlist 对其进行验证。

### 参数

#### `[dir]`

项目目录。默认为当前目录。

### Flag

#### `--env`

目标环境名称。默认为 `production`。未设置 `--env-file` 时，会从项目目录自动选择 `.env.<name>`。如果环境不存在，CLI 会在确认后创建该环境。

#### `--org`

组织 ID。也可以通过 `MASTRA_ORG_ID` 环境变量设置。

#### `--project`

项目 ID、slug 或名称。也可以通过 `MASTRA_PROJECT_ID` 环境变量设置。如果没有匹配的项目，该值将用作部署时创建的新项目名称。

#### `-y, --yes`

无需确认提示，自动接受默认选项，包括创建项目和环境。

#### `-c, --config`

项目配置文件的路径。默认为 `.mastra-project.json`。

#### `--env-file`

要随部署一起打包的 env 文件路径（相对于项目目录）。设置后，会禁用基于 `--env` 自动选择 `.env.<name>` 的行为。

```bash
mastra deploy --env staging --env-file .env.staging.local
```

#### `--region`

新建环境所在的区域（例如 `eu`）。仅在 CLI 创建环境时应用。

#### `--skip-build`

跳过构建步骤，部署现有的 `.mastra/output` 目录。如果现有构建相对于当前源代码已经过期，CLI 会发出警告。

#### `--skip-preflight`

跳过上传前对构建输出的验证。

#### `--debug`

在构建步骤中启用 debug 日志。

### CI/CD 用法

对于 headless 部署，请将 `MASTRA_API_TOKEN`、`MASTRA_ORG_ID` 和 `MASTRA_PROJECT_ID` 设置为环境变量。设置 `MASTRA_API_TOKEN` 后会自动跳过交互式提示。与 `--yes` 结合使用可自动接受创建环境。

```bash
export MASTRA_API_TOKEN="..."
export MASTRA_ORG_ID="..."
export MASTRA_PROJECT_ID="..."
mastra deploy --env staging --yes
```

## `mastra env`

管理 Mastra 平台上的环境。环境是属于某个项目的部署目标（例如 `production`、`staging`、`preview-42`）。当前组织从存储的凭据中解析。

每个子命令都按固定顺序解析项目。它首先检查 `MASTRA_PROJECT_ID` 环境变量和 `--project <name|slug|id>` flag，然后读取当前目录中由 [`mastra deploy`](#mastra-deploy) 写入的 `.mastra-project.json` 文件。只要从项目目录运行命令，就无需指定项目。

### `mastra env list`

列出项目的环境。每个环境都会显示其最新部署（正在处理流量时带有 `(active)` 标记），以及附加数据库等托管资源注入的环境变量名称。

```bash
mastra env list
```

#### `--json`

输出机器可读的 JSON。仅包含非敏感 metadata（ID、名称、slug、类型、区域、分支、URL、托管环境变量名称及最新部署状态），因此可以安全地记录在 CI 日志中。

### `mastra env create`

为项目创建新环境。

```bash
mastra env create staging --type staging --region eu
```

#### `-t, --type`

环境类型。可选值为 `production`、`staging` 或 `preview`。默认为 `staging`。

#### `-r, --region`

环境所在的区域（例如 `eu`）。

#### `--json`

输出机器可读的 JSON。与 [`mastra env list`](#mastra-env-list) 一样，敏感字段会被省略。

### `mastra env delete`

删除环境。

```bash
mastra env delete <env>
```

`<env>` 可以是环境名称、slug 或 ID。除非传入 `--yes`，否则 CLI 会提示确认。

#### `-y, --yes`

跳过确认提示。

### `mastra env restart`

重新启动环境中正在运行的服务，使保存的环境变量（包括附加数据库提供的托管变量）立即生效，无需重新部署。

```bash
mastra env restart <env>
```

`<env>` 可以是环境名称、slug 或 ID。如果该环境从未部署过，命令会因冲突错误而失败。

### `mastra env vars pull`

将环境的环境变量拉取到本地 env 文件（默认为 `.env`）。该文件包含部署使用的合并变量集：环境中存储的变量（例如在 dashboard 的环境编辑器中添加的变量）与项目级变量。发生冲突时，项目值优先。附加数据库注入的托管变量会以注释形式列出（仅列名称），因为其值是由平台管理的 secret。

```bash
mastra env vars pull
mastra env vars pull <env> --output .env.staging
```

`<env>` 可以是环境名称、slug 或 ID；当项目只有一个环境时，可以省略。文件将以 `0600` 权限写入。如果输出文件已存在，命令会停止。传入 `--force` 可替换该文件。

#### `-o, --output`

要写入的文件。默认为 `.env`。

#### `-f, --force`

替换现有输出文件。

### `mastra env db`

管理附加到 Mastra 平台项目的数据库。数据库由托管 Provider（例如 Turso 或 Neon）预配，并自动将其连接环境变量注入部署。

数据库可以是 **environment-scoped**（其环境变量仅提供给一个环境），也可以是 **shared**（project-scoped：其环境变量提供给所有环境）。`mastra env db create` 默认创建 environment-scoped 数据库：传入环境参数，或让 CLI 自动选择或提示选择。创建时传入 `--shared` 可改为附加共享数据库。对于其他子命令（`list`、`delete`、`keys`），传入环境参数可操作 environment-scoped 数据库；省略则操作共享数据库。

创建和删除数据库需要在组织中拥有 `admin` 角色。

### `mastra env db list`

列出附加到项目的数据库，包括 Provider、预配状态、作用域（每个数据库向哪个环境提供变量），以及每个数据库注入的环境变量名称。传入环境后，只显示向该环境提供变量的数据库（environment-scoped 和 shared）。

```bash
mastra env db list
mastra env db list <env>
```

#### `--json`

输出机器可读的 JSON。

### `mastra env db create`

预配并附加托管数据库，然后轮询直至数据库就绪。预配错误会连同 Provider 的错误详情一起输出。

默认情况下，数据库仅作用于一个环境：传入环境参数来选择该环境，或省略参数让 CLI 代为选择。项目只有一个环境时，会使用该环境。有多个环境时，CLI 会提示你进行交互式选择；在非交互式上下文（CI、`--json`）中则必须提供环境参数。也可以传入 `--shared`，附加由所有环境共享的 project-scoped 数据库。

Environment-scoped 数据库会从环境继承 Provider 区域。共享数据库接受 `--region`。

```bash
mastra env db create --kind turso                                    # picks or prompts for an environment
mastra env db create staging --kind turso                            # scoped to the "staging" environment
mastra env db create --kind turso --shared                           # shared by all environments
mastra env db create --kind neon --name my-app-db --region aws-us-east-1 --shared
```

#### `--kind`

数据库 Provider（必填）。可选值为 `turso` 或 `neon`。

#### `--name`

数据库名称。默认为根据项目 slug 派生的名称（例如 `my-app-db`）。

#### `--region`

共享数据库的 Provider 区域 ID。对于 environment-scoped 数据库，该选项会被忽略。

#### `--shared`

附加为由所有环境共享的 project-scoped 数据库。不能与环境参数同时使用。

#### `--no-wait`

附加请求进入队列后立即返回，不轮询等待数据库就绪。稍后可以使用 `mastra env db show` 查看进度。

#### `--json`

输出机器可读的 JSON。在此模式下，如果项目有多个环境，则必须提供环境参数或 `--shared`（不会显示交互式提示）。

### `mastra env db show`

显示数据库详情，并在数据库就绪后显示其连接环境变量。默认会掩码 secret 值。

```bash
mastra env db show <database>
```

`<database>` 可以是数据库 ID 或名称。

#### `--show-secrets`

输出 secret 连接值，而不是将其掩码。

#### `--json`

输出机器可读的 JSON。除非传入 `--show-secrets`，否则 secret 值会被掩码。

### `mastra env db delete`

从 Provider 永久删除数据库，包括其中的所有数据。此操作无法撤销。除非传入 `--yes`，否则 CLI 会提示确认。删除后，部署将不再收到该数据库的环境变量。

```bash
mastra env db delete <database>
```

#### `-y, --yes`

跳过确认提示。

### `mastra env deploys`

按从新到旧的顺序列出项目部署。正在处理流量的部署会标记为 `(active)`。

```bash
mastra env deploys [environment]
```

省略 `[environment]` 可显示所有环境的部署；传入环境名称、slug 或 ID 可筛选特定环境。

#### `--json`

输出机器可读的 JSON。

## `mastra studio deploy`

> **信息:** `mastra studio deploy` 仍可使用，但已由 [`mastra deploy`](#mastra-deploy) 取代。后者支持在单个项目中使用多个环境（`--env staging`、`--env production`）。新设置应使用 `mastra deploy`。

构建项目并将其部署到 Mastra 平台。需要通过 [`mastra auth login`](#mastra-auth-login) 或 `MASTRA_API_TOKEN` 环境变量进行身份验证。

```bash
mastra studio deploy
```

该命令会运行 `mastra build` 并压缩输出。将所有内容上传到平台之前，它会从项目目录读取 env 文件。上传后，它会轮询部署状态并流式输出构建日志，直到部署进入终止状态。

部署命令会自动加载项目的 `.env` 文件。如果 `MASTRA_PROJECT_ID` 指向为 Observability 预配的项目，部署会链接到该项目，而不是创建新项目。将 Studio 部署到仅用于 Observability 的项目，会在平台端将其转换为 Studio 项目。

CLI 要求项目目录中至少存在一个 `.env` 或 `.env.*` 文件（不包括 `.env.example`）；否则会失败并显示 `Error: No env file found for deploy.`。存在多个 env 文件时，CLI 会提示选择一个（默认为 `.env.production`）。传入 `--env-file` 可明确选择。使用 `--yes` 且存在多个 env 文件时，必须传入 `--env-file`，否则部署会出错。

组织和项目按以下顺序解析：环境变量 flag、`.mastra-project.json` 配置文件、凭据中的当前组织，最后是交互式提示。首次部署时，CLI 会将解析出的 ID 保存到 `.mastra-project.json`，后续部署便会跳过提示。

如果 `--project <value>` 与现有项目的 ID 或 slug 不匹配，CLI 会将 `<value>` 视为新项目名称，并在确认后创建项目。与 `--yes` 结合使用时，可通过一条非交互式命令创建并部署新项目：

```bash
mastra studio deploy --project "my-new-project" --yes
```

### 参数

#### `[dir]`

项目目录。默认为当前目录。

### Flag

#### `--org`

组织 ID。也可以通过 `MASTRA_ORG_ID` 环境变量设置。

#### `--project`

项目 ID 或 slug。也可以通过 `MASTRA_PROJECT_ID` 环境变量设置。如果没有匹配的项目，该值将用作部署时创建的新项目名称。

#### `-y, --yes`

无需确认提示，自动接受默认选项。

#### `-c, --config`

项目配置文件的路径。默认为 `.mastra-project.json`。

#### `--env-file`

要随部署一起打包的 env 文件路径（相对于项目目录）。可以通过指向不同的 env 文件（例如 `.env.staging`、`.env.production`），将同一项目部署到多个环境。

```bash
mastra studio deploy --env-file .env.staging --yes
```

#### `--skip-build`

跳过构建步骤，部署现有的 `.mastra/output` 目录。

#### `--debug`

在构建步骤中启用 debug 日志。

### CI/CD 用法

对于 headless 部署，请将 `MASTRA_API_TOKEN`、`MASTRA_ORG_ID` 和 `MASTRA_PROJECT_ID` 设置为环境变量。设置 `MASTRA_API_TOKEN` 后会自动跳过交互式提示。

### `mastra studio deploy list`

列出所有项目及其最新部署状态和 URL。

### `mastra studio deploy status`

显示指定部署的状态。

```bash
mastra studio deploy status <deploy-id>
```

#### `--watch, -w`

轮询状态变化，直到部署进入终止状态。

### `mastra studio deploy logs`

显示指定部署的日志。

```bash
mastra studio deploy logs <deploy-id>
```

#### `--follow, -f`

实时流式输出日志。

#### `--tail`

要显示的最近日志行数。

### `mastra studio deploy suggestions`

显示 Studio 部署失败的诊断结果和建议修复方案。

```bash
mastra studio deploy suggestions [deploy-id]
```

如果省略 `deploy-id`，该命令会使用已链接项目的最新部署。如果诊断尚不存在，命令会启动诊断并轮询直至结果就绪。只有诊断发现问题时，才会显示建议。

### `mastra studio projects`

列出当前组织中的所有项目。

### `mastra studio projects create`

通过交互式提示创建新项目。此命令不接受 `--name` flag；如需以非交互方式创建项目，请改用 [`mastra studio deploy --project <name> --yes`](#mastra-studio-deploy)，它会一次性创建并部署项目。

## `mastra server deploy`

> **信息:** `mastra server deploy` 仍可使用，但已由 [`mastra deploy`](#mastra-deploy) 取代。后者可以将单个项目部署到多个环境，无需分别使用 Studio 和 Server 命令。新设置应使用 `mastra deploy`。

构建项目并将其部署到 Mastra 平台上的 Server。其工作方式与 [`mastra studio deploy`](#mastra-studio-deploy) 相同，使用相同的 flag、参数和解析逻辑。

部署命令会自动加载项目的 `.env` 文件。如果 `MASTRA_PROJECT_ID` 指向为 Observability 预配的项目，部署会链接到该项目，而不是创建新项目。将 Server 部署到仅用于 Observability 的项目，会在平台端将其转换为 Server 项目。

```bash
mastra server deploy [dir]
```

### `mastra server deploy suggestions`

显示 Server 部署失败的诊断结果和建议修复方案。

```bash
mastra server deploy suggestions [deploy-id]
```

如果省略 `deploy-id`，该命令会使用已链接项目的最新部署。如果诊断尚不存在，命令会启动诊断并轮询直至结果就绪。只有诊断发现问题时，才会显示建议。

## `mastra server pause`

暂停已链接项目中正在运行的服务器实例。组织和项目的解析方式与 [`mastra server deploy`](#mastra-server-deploy) 相同。

```bash
mastra server pause
```

### Flag

#### `--org`

组织 ID。也可以通过 `MASTRA_ORG_ID` 环境变量设置。

#### `--project`

未设置 `MASTRA_PROJECT_ID` 时使用的项目 ID 或 slug。Slug 会在当前组织的项目中进行解析。

#### `-c, --config`

项目配置文件的路径。默认为 `.mastra-project.json`。

如果实例未在运行，命令会失败。

## `mastra server restart`

重新启动已链接项目中暂停或停止的服务器实例。平台接受重启请求后，CLI 会解析 deploy ID（从 API 响应获取；如果响应中没有 ID，则轮询项目和部署 metadata），随后像 [`mastra server deploy`](#mastra-server-deploy) 一样流式输出构建与部署日志，直到部署进入终止状态。

### Flag

与 [`mastra server pause`](#mastra-server-pause) 使用相同的 flag：**`--org`**、**`--project`** 和 **`-c` / `--config`**，默认值和行为也相同。

```bash
mastra server restart
```

如果该项目仍有活动部署（正在运行、构建、部署等），命令会失败。这是平台限制，确保你无法在另一个部署进行期间重启。

## `mastra server env`

管理已链接服务器部署的环境变量。组织和项目的解析方式与 [`mastra server deploy`](#mastra-server-deploy) 相同。

每个子命令都接受 `-c` / `--config`，用于指定项目配置文件路径（默认为 `.mastra-project.json`）。

### `mastra server env list`

列出已链接项目的所有环境变量。输出中的值会被部分掩码。

### `mastra server env set`

设置环境变量。CLI 会读取当前 map、应用更改并上传结果。

```bash
mastra server env set <key> <value>
```

### `mastra server env unset`

移除环境变量。

```bash
mastra server env unset <key>
```

### `mastra server env import`

从文件（例如 `.env` 文件）导入变量，并将其合并到现有 map。新值会覆盖服务器上已存在的 key。

```bash
mastra server env import <file>
```

### `mastra server env pull`

从已链接项目下载环境变量并写入本地文件。此操作与 [`mastra server env import`](#mastra-server-env-import) 相反。

```bash
mastra server env pull [file]
```

未提供参数时，文件默认为 `.env`。所有值均使用双引号包裹并进行转义，以便安全地在 shell 中 source。不是有效 shell 标识符的 key 会被跳过。由于文件包含 secret，输出文件会以严格权限（`0600`）创建。

#### `--project`

项目 ID 或 slug。未设置 `MASTRA_PROJECT_ID` 时，覆盖已链接项目。

#### CI 用法

在持续集成 pipeline 中，请使用 `MASTRA_API_TOKEN` 进行身份验证，并在运行应用前拉取环境：

```bash
export MASTRA_API_TOKEN="..."
mastra server env pull .env.production --project my-project
```

## `mastra auth`

管理 Mastra 平台的身份验证。凭据存储在 `~/.mastra/credentials.json`。你也可以设置 `MASTRA_API_TOKEN` 环境变量，代替交互式登录。

### `mastra auth login`

打开浏览器进行登录，并在本地存储凭据。

### `mastra auth logout`

移除存储的凭据。如果环境中仍设置了 `MASTRA_API_TOKEN`，CLI 会警告该变量将继续使用。

### `mastra auth whoami`

显示当前用户的电子邮件、用户 ID 和活动组织。

### `mastra auth orgs`

列出所有组织以及你在每个组织中的角色。当前组织会带有标记。

#### `mastra auth orgs switch`

通过交互式提示切换活动组织。设置 `MASTRA_API_TOKEN` 或 `MASTRA_ORG_ID` 环境变量后无法使用。

### `mastra auth tokens`

列出所有 API token 及其最近使用日期。

#### `mastra auth tokens create`

创建新的 API token。Secret 只显示一次，之后无法再次获取。

```bash
mastra auth tokens create <name>
```

#### `mastra auth tokens revoke`

撤销 API token。

```bash
mastra auth tokens revoke <token-id>
```

## `mastra lint`

`mastra lint` 命令用于验证 Mastra 项目的结构和代码。

默认情况下，`mastra lint` 会检查源文件和配置中的项目问题。使用 `--preflight` 还可以在部署前检查 `.mastra/output` 中的 bundle。

```bash
mastra lint --preflight
```

该命令接受[通用 flag](#common-flags)。

### Flag

#### `--preflight`

对构建后的 Mastra 输出运行部署 preflight 检查。除非同时传入 `--skip-build`，否则会在检查前构建项目。

#### `--skip-build`

跳过构建步骤，复用现有的 `.mastra/output` 目录。此 flag 仅在设置 `--preflight` 时适用。

#### `--env-file <file>`

使用指定的环境文件进行 preflight 验证。此 flag 仅在设置 `--preflight` 时适用。

#### `--strict`

将警告视为错误。

#### `--json`

输出机器可读的 JSON。

#### `--debug`

启用 debug 日志。

## `mastra scorers`

`mastra scorers` 命令提供评估 Scorer 管理功能，用于衡量 AI 生成输出的质量、准确性和性能。

阅读 [Scorer 概述](https://mastra.zisheng.pro/docs/evals/overview)了解详情。

### `add`

向项目添加新 Scorer。你可以使用交互式提示：

```bash
mastra scorers add
```

也可以直接提供 Scorer 名称：

```bash
mastra scorers add answer-relevancy
```

使用 [`list`](#list) 命令获取正确的 ID。

### `list`

列出所有可用的 Scorer 模板。将相应 ID 用于 `add` 命令。

## `mastra create`

使用与 [`create-mastra`](https://mastra.zisheng.pro/reference/cli/create-mastra) 相同的项目创建流程，创建独立的 Mastra 项目。

**npm**:

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

**pnpm**:

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

**Yarn**:

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

**Bun**:

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

同时提供项目名称和 `--llm` 可跳过交互式设置提示。使用 `--template [template]` 可指定任意模板，使用 `--empty` 可创建不含 Provider 的最小 scaffold。

该命令会为检测到的编程助手安装 Mastra Skill，并在适当时初始化 Git。使用 `--no-skills` 或 `--no-git` 可选择退出。

有关模式行为、冲突、验证和完整 flag 说明，请参阅 [`create-mastra` reference](https://mastra.zisheng.pro/reference/cli/create-mastra)。

## `mastra init`

`mastra init` 命令用于在现有项目中初始化 Mastra。使用此命令可以 scaffold 所需的文件夹和配置，无需从头生成新项目。

### Flag

该命令接受以下额外 flag：

#### `--default`

使用 OpenAI 在 `src` 内创建文件。它还会使用示例代码填充 `src/mastra` 文件夹。

#### `--dir`

Mastra 文件的保存目录。默认为 `src`。

#### `--components`

要添加的组件列表，以逗号分隔。每个组件都会创建一个新文件夹。可选值：`"agents" | "tools" | "workflows" | "scorers"`。默认为 `['agents', 'tools', 'workflows']`。

#### `--llm`

默认模型 Provider。可选值：`"openai" | "anthropic" | "groq" | "google" | "cerebras" | "mistral"`。

#### `--llm-api-key`

所选模型 Provider 的 API key。将写入环境变量文件（`.env`）。

#### `--example`

启用后，会为组件列表写入示例代码（例如 Agent 示例代码）。

#### `--no-example`

不包含示例代码。使用 `--default` flag 时很有用。

#### `--mcp`

为代码编辑器配置 Mastra 的 MCP server。可选值：`"cursor" | "cursor-global" | "windsurf" | "vscode"`。

#### `--observability`

在 Mastra 平台上启用 Observability。CLI 会提示你选择现有平台项目或创建新项目，然后写入所需环境变量并配置 Observability exporter。

#### `--no-observability`

跳过 Mastra Observability 提示。

#### `--observability-project`

设置启用 Mastra Observability 时使用的平台项目名称。

## `mastra migrate`

运行数据库 migration 以更新 Storage schema。升级到包含 Storage schema 更改的 Mastra 版本时，此命令非常有用。

该命令会打包项目并连接到已配置的 Storage backend，然后执行所有待处理 migration。目前支持：

- **重复 span migration**：移除重复的 `(traceId, spanId)` 条目，并添加唯一约束以确保数据完整性。
- **ClickHouse legacy-to-vNext span migration**：将历史 span 从旧版 `mastra_ai_spans` 表复制到 vNext `mastra_span_events` schema。该操作会分批运行，以保持在内存限制内。有关详情，请参阅 [ClickHouse Storage reference](https://mastra.zisheng.pro/reference/storage/clickhouse)。

```bash
mastra migrate
```

有关何时需要 migration 的详情，请参阅 [Storage migration 指南](https://mastra.zisheng.pro/guides/migrations/upgrade-to-v1/storage)。

该命令接受[通用 flag](#common-flags)。

## `mastra api`

使用 JSON 输入和 JSON 输出调用 Mastra runtime 服务器。它适用于本地开发服务器、已部署的 Mastra 平台项目、自托管 Mastra 服务器或托管的 Mastra Platform Observability API。

```bash
mastra api agent list
mastra api agent run weather-agent '{"messages":"What is the weather in London?"}'
mastra api tool execute get-weather '{"location":"San Francisco"}'
mastra api trace list '{"page":0,"perPage":20}'
```

使用 `mastra api <resource> <action> --help` 查看命令示例。

### 输出

成功响应会以 JSON 形式写入 `stdout`。单资源命令返回：

```json
{ "data": {} }
```

列表命令返回 `data` 数组和分页 metadata：

```json
{ "data": [], "page": { "total": 0, "page": 0, "perPage": 0, "hasMore": false } }
```

错误会以 JSON 形式写入 `stderr`，并返回非零退出码：

```json
{
  "error": {
    "code": "SERVER_UNREACHABLE",
    "message": "Could not connect to target server",
    "details": {}
  }
}
```

### 目标解析

对于 runtime 命令，该命令按以下顺序解析目标服务器：

1. 通过 `--url <url>` 指定的远程或自托管服务器。
2. 本地 `mastra dev` 服务器 `http://localhost:4111`。
3. Mastra 平台项目的 `.mastra-project.json`。

只有当 CLI 从 `.mastra-project.json` 解析出 Mastra 平台目标时，才会使用自动平台身份验证。Localhost 目标和显式 `--url` 目标不会自动获得凭据。通过 `--header` 传入的 header 会发送到所有目标，包括 localhost。

对于 Observability 命令（`trace`、`log`、`score` 和 `metric`），CLI 默认以 `https://observability.mastra.ai` 为目标，而不是项目部署 URL。Trace Intelligence 命令（`learning`）的工作方式相同，但目标为 `https://output.signals.mastra.ai`。两者均按以下顺序解析凭据：

1. 通过 `--header` 显式传入的 `Authorization` 和 `X-Mastra-Project-Id` header。
2. 环境中的 `MASTRA_PLATFORM_ACCESS_TOKEN` 和 `MASTRA_PROJECT_ID`。
3. `.mastra-project.json` 中用于项目 ID 的项目 metadata。
4. 作为身份验证回退方案的 Mastra CLI 登录 token。

Learning 命令还会发送 `X-Mastra-Organization-Id`，解析顺序为：显式 `--header`、环境中的 `MASTRA_ORGANIZATION_ID`，然后是 `.mastra-project.json`。

如需覆盖默认的托管 Observability 目标或凭据，请使用 `--url` 和 `--header`。

### Flag

#### `--url <url>`

指定目标 Mastra 服务器 URL。

```bash
mastra api --url https://example.com agent list
```

#### `--server-api-prefix <prefix>`

设置目标服务器的 API route prefix。默认为 `/api`。当服务器挂载在自定义 prefix 下时使用此选项（例如 `@mastra/fastify` `MastraServer` 使用 `prefix: "/api/mastra-studio"`），其方式与 `mastra studio` 接受 `--server-api-prefix` 相同。也可以设置 `MASTRA_API_PREFIX` 环境变量，无需传入该 flag。

```bash
mastra api --url https://example.com --server-api-prefix /api/mastra-studio agent list
```

#### `--header <"Key: Value">`

发送自定义 HTTP header。重复使用该 flag 可发送多个 header。

```bash
mastra api --url https://example.com --header "Authorization: Bearer $TOKEN" agent list
```

#### `--timeout <ms>`

设置请求超时时间（毫秒）。默认为 `30000`。Workflow run 的 start 和 resume 命令默认为 `120000`。

#### `--pretty`

美化 JSON 输出。默认为 `false`。

#### `--schema`

输出接受 JSON 输入的命令所使用的 CLI 请求 schema。该 schema 来自目标服务器的 route contract，包括命令结构、位置参数、示例、请求 schema 和响应结构。

`--schema` 可用于接受 JSON 输入的叶级命令，但不能作为顶层 `mastra api` flag 使用。

```bash
mastra api agent run --schema
mastra api tool execute --schema
```

### 输入模型

接受输入的命令会接收一个内联 JSON 参数。不要传入文件路径或 stdin。

```bash
mastra api workflow run start data-pipeline '{"inputData":{"source":"s3://bucket/data.csv"}}'
```

稳定 ID 使用位置参数，筛选条件或 payload 使用 JSON。对于同时需要 query 参数和 request body 的 route，请传入一个 JSON 对象。CLI 会根据服务器 route schema 拆分输入。

```bash
mastra api thread create '{"agentId":"weather-agent","resourceId":"user_123","threadId":"thread_abc123","title":"Support conversation"}'
```

目标 route 支持分页时，列表命令接受 JSON 输入中的 `page` 和 `perPage`：

```bash
mastra api score list '{"page":0,"perPage":50}'
mastra api trace list '{"page":0,"perPage":20}'
```

支持筛选的 route 会在同一个 JSON 输入中接受筛选条件。例如，Observability Trace 列表支持分页和 route 支持的筛选条件：

```bash
mastra api trace list '{"page":0,"perPage":20,"filters":{"spanType":"agent"}}'
```

### 获取特定命令的帮助

每个 `mastra api` 叶级命令的帮助输出中都包含针对该命令的示例。请对要调用的具体命令使用 `--help`：

```bash
mastra api agent run --help
mastra api tool execute --help
mastra api memory current update --help
mastra api workflow run resume --help
```

对于接受 JSON 输入的命令，可使用 `--schema` 检查目标服务器返回的请求结构：

```bash
mastra api agent run --schema
mastra api thread create --schema
mastra api score create --schema
```

部分命令有重要的 runtime 要求。例如，`mastra api memory current update` 要求为 Memory 实例启用 working memory，而 `mastra api workflow run resume` 仅适用于已暂停的 Workflow run。

### 命令

#### `mastra api agent list`

列出目标服务器上注册的 Agent。可以传入可选 JSON 输入，使用 route 支持的筛选条件。

```bash
mastra api agent list [input]
```

#### `mastra api agent get`

获取一个已注册 Agent 的 metadata。

```bash
mastra api agent get <agentId>
```

#### `mastra api agent run`

使用 JSON 输入运行 Agent。有关文本提示、聊天消息和 Memory thread 选项的示例，请查看命令帮助。

```bash
mastra api agent run <agentId> <input>
```

#### `mastra api workflow list`

列出目标服务器上注册的 Workflow。可以传入可选 JSON 输入，使用 route 支持的筛选条件。

```bash
mastra api workflow list [input]
```

#### `mastra api workflow get`

获取一个已注册 Workflow 的 metadata。

```bash
mastra api workflow get <workflowId>
```

#### `mastra api workflow run start`

使用 JSON 输入启动 Workflow run。由于 run 可能需要更长时间才能完成，Workflow start 命令使用的默认超时时间比大多数命令更长。

```bash
mastra api workflow run start <workflowId> <input>
```

#### `mastra api workflow run list`

列出 Workflow 的 run。可以传入可选 JSON 输入，使用 route 支持的筛选条件或分页。

```bash
mastra api workflow run list <workflowId> [input]
```

#### `mastra api workflow run get`

按 ID 获取一个 Workflow run。

```bash
mastra api workflow run get <workflowId> <runId>
```

#### `mastra api workflow run resume`

使用 JSON 输入恢复已暂停的 Workflow run。该 run 必须处于暂停状态。

```bash
mastra api workflow run resume <workflowId> <runId> <input>
```

#### `mastra api workflow run cancel`

取消 Workflow run。

```bash
mastra api workflow run cancel <workflowId> <runId>
```

#### `mastra api tool list`

列出目标服务器上注册的 Tool。可以传入可选 JSON 输入，使用 route 支持的筛选条件。

```bash
mastra api tool list [input]
```

#### `mastra api tool get`

获取一个 Tool 的 metadata 和 schema。

```bash
mastra api tool get <toolId>
```

#### `mastra api tool execute`

使用 JSON 输入执行 Tool。除非传入显式 `data` 对象，否则原始 Tool 输入会包装为 route 的 `data` 字段。

```bash
mastra api tool execute <toolId> <input>
```

#### `mastra api mcp list`

列出目标服务器上注册的 Model Context Protocol（MCP）server。可以传入可选 JSON 输入，使用 route 支持的筛选条件。

```bash
mastra api mcp list [input]
```

#### `mastra api mcp get`

获取一个 MCP server 的 metadata。

```bash
mastra api mcp get <id>
```

#### `mastra api mcp tool list`

列出 MCP server 公开的 Tool。可以传入可选 JSON 输入，使用 route 支持的筛选条件。

```bash
mastra api mcp tool list <serverId> [input]
```

#### `mastra api mcp tool get`

获取一个 MCP Tool 的 metadata 和 schema。

```bash
mastra api mcp tool get <serverId> <toolId>
```

#### `mastra api mcp tool execute`

使用 JSON 输入执行 MCP Tool。除非传入显式 `data` 对象，否则原始 Tool 输入会包装为 route 的 `data` 字段。

```bash
mastra api mcp tool execute <serverId> <toolId> <input>
```

#### `mastra api thread list`

列出 Memory thread。可以传入可选 JSON 输入，使用 route 支持的筛选条件。

```bash
mastra api thread list [input]
```

#### `mastra api thread get`

按 ID 获取一个 Memory thread。

```bash
mastra api thread get <threadId>
```

#### `mastra api thread create`

创建 Memory thread。传入一个 JSON 输入对象；服务器 route 要求时，CLI 会将 `agentId` 等字段拆分为 query 参数。

```bash
mastra api thread create <input>
```

#### `mastra api thread update`

更新 Memory thread。为 `agentId`、`resourceId`、`title` 或 `metadata` 等字段传入一个 JSON 输入对象。

```bash
mastra api thread update <threadId> <input>
```

#### `mastra api thread delete`

删除 Memory thread。为 `agentId` 和 `resourceId` 等 route 必需的 query 参数传入 JSON 输入。

```bash
mastra api thread delete <threadId> <input>
```

#### `mastra api thread messages`

列出 Memory thread 的消息。可以传入可选 JSON 输入，使用 route 支持的筛选条件或分页。

```bash
mastra api thread messages <threadId> [input]
```

#### `mastra api memory search`

搜索长期 Memory。使用 `--help` 或 `--schema` 检查 `agentId`、`resourceId` 和 `searchQuery` 等必填字段。

```bash
mastra api memory search <input>
```

#### `mastra api memory current get`

读取 thread 的当前 working memory。

```bash
mastra api memory current get <input>
```

#### `mastra api memory current update`

更新 thread 的当前 working memory。必须为 Memory 实例启用 working memory。

```bash
mastra api memory current update <input>
```

#### `mastra api memory status`

获取 Agent 的 Memory 状态，以及可选的 thread 或资源上下文。

```bash
mastra api memory status <input>
```

#### `mastra api trace list`

列出 Observability Trace。可以传入可选 JSON 输入，使用 route 支持的筛选条件或分页。

```bash
mastra api trace list [input]
mastra api trace list '{"page":0,"perPage":20}'
mastra api trace list '{"page":0,"perPage":20}' --verbose
```

默认情况下，`trace list` 返回轻量的根 span 记录，让你无需获取大量输入、输出、attribute 或 metadata payload 即可翻阅 Trace。传入 `--verbose` 可获取完整的根 span 记录。

#### `mastra api trace get`

获取一个 Observability Trace 的轻量时间线，不获取完整的 span 输入、输出、attribute 或 metadata payload。传入 `--verbose` 可获取完整 Trace payload。

```bash
mastra api trace get <traceId>
mastra api trace get <traceId> --verbose
```

#### `mastra api trace span`

从 Observability Trace 获取一个完整 span。在通过 `trace get` 确定要检查的 span 后使用此命令。

```bash
mastra api trace span <traceId> <spanId>
```

#### `mastra api log list`

列出 Observability 日志。可以传入可选 JSON 输入，使用 route 支持的筛选条件或分页。

```bash
mastra api log list [input]
```

#### `mastra api metric aggregate`

获取单个聚合 metric 值。

```bash
mastra api metric aggregate '{"name":["latency_ms"],"aggregation":"avg"}'
```

#### `mastra api metric breakdown`

获取按 label 或字段分组的 metric 值。

```bash
mastra api metric breakdown '{"name":["latency_ms"],"aggregation":"avg","groupBy":["model"],"limit":10}'
```

#### `mastra api metric timeseries`

获取随时间变化的 metric 值。

```bash
mastra api metric timeseries '{"name":["latency_ms"],"aggregation":"avg","interval":"1h"}'
```

#### `mastra api metric percentiles`

获取随时间变化的 metric 百分位值。百分位值使用 `0` 到 `1` 之间的小数。

```bash
mastra api metric percentiles '{"name":"latency_ms","percentiles":[0.5,0.95,0.99],"interval":"1h"}'
```

#### `mastra api metric names`

列出发现的 metric 名称。可以传入可选 JSON 输入，按 prefix 搜索并限制结果数量。

```bash
mastra api metric names '{"prefix":"lat","limit":10}'
```

#### `mastra api metric label-keys`

列出 metric 的 label key。

```bash
mastra api metric label-keys '{"metricName":"latency_ms"}'
```

#### `mastra api metric label-values`

列出 metric label key 的 label value。可以传入可选的 prefix 和 limit 值来缩小结果范围。

```bash
mastra api metric label-values '{"metricName":"latency_ms","labelKey":"model","prefix":"g","limit":10}'
```

#### 通过 `curl` 使用 Observability

你可以使用平台 access token 和项目 ID 直接调用托管的 Observability API：

```bash
curl -sS "https://observability.mastra.ai/api/observability/traces?page=0&perPage=20" \
  -H "Authorization: Bearer $MASTRA_PLATFORM_ACCESS_TOKEN" \
  -H "X-Mastra-Project-Id: $MASTRA_PROJECT_ID" | jq
```

获取轻量 Trace 时间线：

```bash
curl -sS "https://observability.mastra.ai/api/observability/traces/<trace-id>/light" \
  -H "Authorization: Bearer $MASTRA_PLATFORM_ACCESS_TOKEN" \
  -H "X-Mastra-Project-Id: $MASTRA_PROJECT_ID" | jq
```

获取指定 span：

```bash
curl -sS "https://observability.mastra.ai/api/observability/traces/<trace-id>/spans/<span-id>" \
  -H "Authorization: Bearer $MASTRA_PLATFORM_ACCESS_TOKEN" \
  -H "X-Mastra-Project-Id: $MASTRA_PROJECT_ID" | jq
```

#### `mastra api score create`

创建 Observability score。输入使用服务器的 score body 结构。使用 `--schema` 检查该结构。

```bash
mastra api score create <input>
```

#### `mastra api score list`

列出 Observability score。可以传入可选 JSON 输入，按 run ID 等条件筛选或分页。

```bash
mastra api score list [input]
```

#### `mastra api score get`

按 ID 获取一个 Observability score。

```bash
mastra api score get <scoreId>
```

#### `mastra api dataset list`

列出数据集。可以传入可选 JSON 输入，使用 route 支持的筛选条件或分页。

```bash
mastra api dataset list [input]
```

#### `mastra api dataset get`

按 ID 获取一个数据集。

```bash
mastra api dataset get <datasetId>
```

#### `mastra api dataset create`

使用 JSON 输入创建数据集。

```bash
mastra api dataset create <input>
```

#### `mastra api dataset items`

列出数据集中的条目。可以传入可选 JSON 输入，使用 route 支持的筛选条件或分页。

```bash
mastra api dataset items <datasetId> [input]
```

#### `mastra api experiment list`

列出数据集的实验。可以传入可选 JSON 输入，使用 route 支持的筛选条件或分页。

```bash
mastra api experiment list <datasetId> [input]
```

#### `mastra api experiment get`

按 ID 获取一个实验。

```bash
mastra api experiment get <datasetId> <experimentId>
```

#### `mastra api experiment run`

使用 JSON 输入为数据集启动实验。

```bash
mastra api experiment run <datasetId> <input>
```

#### `mastra api experiment results`

列出实验结果。可以传入可选 JSON 输入，使用 route 支持的筛选条件或分页。

```bash
mastra api experiment results <datasetId> <experimentId> [input]
```

#### `mastra api learning entities`

列出包含 Trace Intelligence 输出的实体（Agent），包括每个实体可用的 Trace signal。需要加入 Trace Intelligence 私有 beta。

```bash
mastra api learning entities '{"entityType":"agent"}'
```

#### `mastra api learning snapshots`

列出某个实体的分析 snapshot，以及按顺序排列、以逗号分隔的 Trace signal 列表。后续命令需要此列表中的 `snapshotId`。

```bash
mastra api learning snapshots <entityId> '{"entityType":"agent","signalNames":"goal,outcome,behavior,sentiment","limit":10}'
```

#### `mastra api learning flow`

获取一个 snapshot 的跨 signal 主题流：用于 Sankey 风格视图的 stage 和 link，其中计数表示不同的 Trace。

```bash
mastra api learning flow <entityId> '{"entityType":"agent","signalNames":"goal,outcome","snapshotId":"<snapshotId>"}'
```

#### `mastra api learning paths`

获取一个 snapshot 中各个 Trace 在有序 Trace signal 中的主题分配。使用 `limit` 和 `offset` 分页。

```bash
mastra api learning paths <entityId> '{"entityType":"agent","signalNames":"goal,outcome","snapshotId":"<snapshotId>","limit":100}'
```

#### `mastra api learning theme list`

列出一个 snapshot 中某个 Trace signal 的主题。

```bash
mastra api learning theme list <entityId> '{"entityType":"agent","signalName":"goal","snapshotId":"<snapshotId>"}'
```

#### `mastra api learning theme get`

根据数字 theme ID 获取一个 snapshot 中的主题。

```bash
mastra api learning theme get <entityId> <themeId> '{"entityType":"agent","signalName":"goal","snapshotId":"<snapshotId>"}'
```

#### `mastra api learning theme examples`

列出一个 snapshot 中某个主题的 Trace 示例。使用 `limit` 和 `offset` 分页。

```bash
mastra api learning theme examples <entityId> <themeId> '{"entityType":"agent","signalName":"goal","snapshotId":"<snapshotId>","limit":10}'
```

#### `mastra api learning theme history`

获取一个持久主题跨 snapshot 的生命周期历史，包括拆分和合并关系。不接受 `snapshotId`。

```bash
mastra api learning theme history <entityId> <themeId> '{"entityType":"agent","signalName":"goal"}'
```

#### `mastra api learning noise get`

获取一个 snapshot 中某个 Trace signal 的未聚类（noise）bucket。

```bash
mastra api learning noise get <entityId> '{"entityType":"agent","signalName":"goal","snapshotId":"<snapshotId>"}'
```

#### `mastra api learning noise examples`

列出一个 snapshot 中 noise bucket 的 Trace 示例。使用 `limit` 和 `offset` 分页。

```bash
mastra api learning noise examples <entityId> '{"entityType":"agent","signalName":"goal","snapshotId":"<snapshotId>","limit":10}'
```

## 通用 flag

### `--dir`

**适用于：** `dev`、`build`、`lint`、`migrate`

Mastra 文件夹的路径。默认为 `src/mastra`。

### `--debug`

**适用于：** `dev`、`build`、`migrate`

为 Mastra 内部启用详细日志。默认为 `false`。

### `--env`

**适用于：** `dev`、`start`、`studio`、`migrate`

要包含的自定义环境变量文件。默认包含 `.env.development`、`.env.local` 和 `.env`。

### `--root`

**适用于：** `dev`、`build`、`lint`、`migrate`

根文件夹的路径。默认为 `process.cwd()`。

### `--tools`

**适用于：** `dev`、`build`、`lint`

要包含的 Tool 路径列表，以逗号分隔。默认为 `src/mastra/tools`。

## 全局 flag

使用以下 flag 获取有关 `mastra` CLI 的信息。

### `--version`

输出 Mastra CLI 版本并退出。

### `--help`

输出帮助消息并退出。

## 遥测

默认情况下，Mastra 会收集有关项目的匿名信息，例如操作系统、Mastra 版本或 Node.js 版本。你可以查看[源代码](https://github.com/mastra-ai/mastra/blob/main/packages/cli/src/analytics/index.ts)，了解收集了哪些信息。

当通过 `mastra dev` 或 `mastra start` 启动的服务器启用了 Observability metric 时，Mastra 还会在启动时发送经过聚合的匿名模型使用情况：每个 Provider 和模型的输入与输出 token 数量，以及命令（`dev` 或 `start`）和 `NODE_ENV`。绝不会发送提示、响应或其他消息内容。你可以查看[源代码](https://github.com/mastra-ai/mastra/blob/main/packages/core/src/telemetry/usage-telemetry.ts)，了解收集了哪些信息。

服务器启动时，Mastra 还会发送匿名的项目功能面 snapshot：已注册 Agent、Agent controller、Workflow、Tool、Processor、Vector Store、Scorer、Workspace、MCP server、Gateway 和 Channel 的数量，以及 Memory、Voice、Editor 和 Observability 使用情况的布尔值与粗粒度 Storage backend 类别。它不会发送名称或标识符。你可以查看[源代码](https://github.com/mastra-ai/mastra/blob/main/packages/core/src/telemetry/feature-telemetry.ts)，了解收集了哪些信息。

设置环境变量即可选择退出所有 CLI 和使用情况分析：

```bash
MASTRA_TELEMETRY_DISABLED=1
```

也可以在使用其他 `mastra` 命令时设置该变量：

```bash
MASTRA_TELEMETRY_DISABLED=1 mastra dev
```