命令行指令

🌐 CLI Commands

你可以使用 Mastra 提供的命令行接口 (CLI) 来开发、构建并启动你的 Mastra 项目。

🌐 You can use the Command-Line Interface (CLI) provided by Mastra to develop, build, and start your Mastra project.

mastra dev

启动一个服务器，为你的代理、工具和工作流提供 Studio 和 REST 端点。一旦 mastra dev 运行，你可以访问 http://localhost:4111/swagger-ui 来查看所有可用端点的概览。

🌐 Starts a server which exposes Studio and REST endpoints for your agents, tools, and workflows. You can visit http://localhost:4111/swagger-ui for an overview of all available endpoints once mastra dev is running.

你也可以配置服务器。

🌐 You can also configure the server.

标志

🌐 Flags

该命令接受 常见标志 以及以下附加标志：

🌐 The command accepts common flags and the following additional flags:

--https

启用本地 HTTPS 支持。了解更多。

🌐 Enable local HTTPS support. Learn more.

--inspect

以调试模式启动开发服务器，有助于调试。可以选择指定自定义的主机和端口（例如，Docker 中的 --inspect=0.0.0.0:9229）。这不能与 --inspect-brk 一起使用。

🌐 Start the development server in inspect mode, helpful for debugging. Optionally specify a custom host and port (e.g., --inspect=0.0.0.0:9229 for Docker). This can't be used together with --inspect-brk.

--inspect-brk

在检查模式下启动开发服务器，并在脚本开始处中断。可以选择指定自定义主机和端口（例如，--inspect-brk=0.0.0.0:9229）。这不能与 --inspect 一起使用。

🌐 Start the development server in inspect mode and break at the beginning of the script. Optionally specify a custom host and port (e.g., --inspect-brk=0.0.0.0:9229). This can't be used together with --inspect.

--custom-args

以逗号分隔的自定义参数列表，用于传递给开发服务器。你可以向 Node.js 进程传递参数，例如 --experimental-transform-types。

🌐 Comma-separated list of custom arguments to pass to the development server. You can pass arguments to the Node.js process, e.g. --experimental-transform-types.

配置

🌐 Configs

你可以设置某些环境变量来修改 mastra dev 的行为。

🌐 You can set certain environment variables to modify the behavior of mastra dev.

跳过同级依赖检查

🌐 Skip peer dependency check

将 MASTRA_SKIP_PEERDEP_CHECK=1 设置为在启动时跳过对等依赖版本不匹配检查：

🌐 Set MASTRA_SKIP_PEERDEP_CHECK=1 to skip the peer dependency version mismatch check at startup:

MASTRA_SKIP_PEERDEP_CHECK=1 mastra dev

在单一代码库开发中，当同级依赖可能被更新但包尚未发布时，这非常有用。

🌐 This is useful during monorepo development when peer dependencies may be bumped but packages are not yet published.

禁用构建缓存

🌐 Disable build caching

将 MASTRA_DEV_NO_CACHE=1 设置为强制进行完整重建，而不是使用 .mastra/ 下的缓存资源：

🌐 Set MASTRA_DEV_NO_CACHE=1 to force a full rebuild rather than using the cached assets under .mastra/:

MASTRA_DEV_NO_CACHE=1 mastra dev

当你在调试打包器插件或怀疑输出过时时，这会很有帮助。

🌐 This helps when you are debugging bundler plugins or suspect stale output.

限制并行性

🌐 Limit parallelism

MASTRA_CONCURRENCY 限制了多少昂贵的操作可以并行运行（主要是构建和评估步骤）。例如：

MASTRA_CONCURRENCY=4 mastra dev

保持未设置，让 CLI 为机器选择一个合理的默认值。

🌐 Leave it unset to let the CLI pick a sensible default for the machine.

自定义提供程序端点

🌐 Custom provider endpoints

在使用 Vercel AI SDK 支持的提供商时，你可以通过设置基础 URL 将请求通过代理或内部网关重定向。对于 OpenAI:

🌐 When using providers supported by the Vercel AI SDK you can redirect requests through proxies or internal gateways by setting a base URL. For OpenAI:

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

对于Anthropic：

🌐 For Anthropic:

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

这些会被转发到 Mastra 模型路由，并且可以与任何 "openai/..." 或 "anthropic/..." 模型选择一起使用。

🌐 These are forwarded to the Mastra model router and will work with any "openai/..." or "anthropic/..." model selections.

mastra build

mastra build 命令将你的 Mastra 项目打包成可投入生产的 Hono 服务器。Hono 是一个轻量级、类型安全的 Web 框架，使得将 Mastra 代理部署为带有中间件支持的 HTTP 端点变得非常容易。

🌐 The mastra build command bundles your Mastra project into a production-ready Hono server. Hono is a lightweight, type-safe web framework that makes it easy to deploy Mastra agents as HTTP endpoints with middleware support.

在底层，Mastra 的 Rollup 服务器会定位你的 Mastra 入口文件，并将其打包成可用于生产的 Hono 服务器。在打包过程中，它会对你的代码进行树摇优化，并生成用于调试的源映射。

🌐 Under the hood Mastra's Rollup server locates your Mastra entry file and bundles it to a production-ready Hono server. During that bundling it tree-shakes your code and generates source maps for debugging.

.mastra 中的输出可以使用 mastra start 部署到任何云服务器。

🌐 The output in .mastra can be deployed to any cloud server using mastra start.

如果你要部署到无服务器平台，你需要安装正确的部署工具，以便在 .mastra 中获得正确的输出。

🌐 If you're deploying to a serverless platform you need to install the correct deployer in order to receive the correct output in .mastra.

它接受常见标志。

🌐 It accepts common flags.

标志

🌐 Flags

--studio

将 Studio UI 与构建打包。

🌐 Bundle the Studio UI with the build.

配置

🌐 Configs

你可以设置某些环境变量来修改 mastra build 的行为。

🌐 You can set certain environment variables to modify the behavior of mastra build.

跳过同级依赖检查

🌐 Skip peer dependency check

设置 MASTRA_SKIP_PEERDEP_CHECK=1 以跳过对等依赖版本不匹配检查：

🌐 Set MASTRA_SKIP_PEERDEP_CHECK=1 to skip the peer dependency version mismatch check:

MASTRA_SKIP_PEERDEP_CHECK=1 mastra build

限制并行性

🌐 Limit parallelism

对于 CI 或在资源受限的环境中运行时，你可以通过设置 MASTRA_CONCURRENCY 来限制同时运行的高消耗任务数量。

🌐 For CI or when running in resource constrained environments you can cap how many expensive tasks run at once by setting MASTRA_CONCURRENCY.

MASTRA_CONCURRENCY=2 mastra build

mastra start

info

在使用 mastra start 之前，你需要先运行 mastra build。

🌐 You need to run mastra build before using mastra start.

启动本地服务器，以生产模式提供已构建的 Mastra 应用。默认情况下，OTEL 跟踪 已启用。

🌐 Starts a local server to serve your built Mastra application in production mode. By default, OTEL Tracing is enabled.

标志

🌐 Flags

该命令接受 常见标志 以及以下附加标志：

🌐 The command accepts common flags and the following additional flags:

--dir

生成的 Mastra 输出目录的路径。默认为 .mastra/output。

🌐 The path to your built Mastra output directory. Defaults to .mastra/output.

--no-telemetry

禁用 OTEL 跟踪。

🌐 Disable the OTEL Tracing.

mastra studio

以静态服务器方式启动 Mastra Studio。启动后，你可以输入你的 Mastra 实例 URL（例如 http://localhost:4111）将 Studio 连接到你的 Mastra 后端。

🌐 Starts Mastra Studio as a static server. After starting, you can enter your Mastra instance URL (e.g. http://localhost:4111) to connect Studio to your Mastra backend.

标志

🌐 Flags

该命令接受 常见标志 以及以下附加标志：

🌐 The command accepts common flags and the following additional flags:

--port

运行 Studio 的端口。默认值为 3000。

🌐 The port to run Studio on. Defaults to 3000.

--server-host

要连接的 Mastra API 服务器的主机。默认值为 localhost。

🌐 The host of the Mastra API server to connect to. Defaults to localhost.

--server-port

连接到 Mastra API 服务器的端口。默认为 4111。

🌐 The port of the Mastra API server to connect to. Defaults to 4111.

--server-protocol

连接到 Mastra API 服务器的协议。默认值为 http。

🌐 The protocol of the Mastra API server to connect to. Defaults to http.

mastra lint

mastra lint 命令验证你的 Mastra 项目的结构和代码，以确保其遵循最佳实践且无错误。

🌐 The mastra lint command validates the structure and code of your Mastra project to ensure it follows best practices and is error-free.

它接受常见标志。

🌐 It accepts common flags.

mastra scorers

mastra scorers 命令提供了对评估评分器的管理功能，这些评分器用于衡量 AI 生成输出的质量、准确性和性能。

🌐 The mastra scorers command provides management capabilities for evaluation scorers that measure the quality, accuracy, and performance of AI-generated outputs.

阅读得分手概览以了解更多信息。

🌐 Read the Scorers overview to learn more.

add

向你的项目添加一个新的评分器。你可以使用交互式提示：

🌐 Add a new scorer to your project. You can use an interactive prompt:

mastra scorers add

或者直接提供评分者名称：

🌐 Or provide a scorer name directly:

mastra scorers add answer-relevancy

使用 list 命令获取正确的 ID。

🌐 Use the list command to get the correct ID.

list

列出所有可用的评分器模板。使用 ID 作为 add 命令。

🌐 List all available scorer templates. Use the ID for the add command.

mastra init

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

🌐 The mastra init command initializes Mastra in an existing project. Use this command to scaffold the necessary folders and configuration without generating a new project from scratch.

标志

🌐 Flags

该命令接受以下附加标志：

🌐 The command accepts the following additional flags:

--default

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

🌐 Creates files inside src using OpenAI. It also populates the src/mastra folders with example code.

--dir

Mastra 文件应保存到的目录。默认是 src。

🌐 The directory where Mastra files should be saved to. Defaults to src.

--components

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

🌐 Comma-separated list of components to add. For each component a new folder will be created. Choose from: "agents" | "tools" | "workflows" | "scorers". Defaults to ['agents', 'tools', 'workflows'].

--llm

默认模型提供商。可选择："openai" | "anthropic" | "groq" | "google" | "cerebras" | "mistral"。

🌐 Default model provider. Choose from: "openai" | "anthropic" | "groq" | "google" | "cerebras" | "mistral".

--llm-api-key

你选择的模型提供商的 API 密钥。将写入环境变量文件（.env）。

🌐 The API key for your chosen model provider. Will be written to an environment variables file (.env).

--example

如果启用，示例代码会被写入组件列表中（例如示例代理代码）。

🌐 If enabled, example code is written to the list of components (e.g. example agent code).

--no-example

不要包含示例代码。在使用 --default 标志时很有用。

🌐 Do not include example code. Useful when using the --default flag.

--mcp

使用 Mastra 的 MCP 服务器配置你的代码编辑器。可选项："cursor" | "cursor-global" | "windsurf" | "vscode"。

🌐 Configure your code editor with Mastra's MCP server. Choose from: "cursor" | "cursor-global" | "windsurf" | "vscode".

mastra migrate

运行数据库迁移以更新存储架构。当升级包含存储架构更改的 Mastra 版本时，此命令非常有用。

🌐 Runs database migrations to update your storage schema. This command is useful when upgrading Mastra versions that include storage schema changes.

该命令会打包你的项目，连接到你配置的存储后端，并执行任何待处理的迁移。目前支持：

🌐 The command bundles your project, connects to your configured storage backend, and executes any pending migrations. Currently supports:

• 重复跨度迁移：删除重复的 (traceId, spanId) 条目，并添加唯一约束以确保数据完整性。

mastra migrate

有关何时需要迁移的详细信息，请参阅存储迁移指南。

🌐 See the Storage migration guide for details on when migrations are needed.

它接受常见标志。

🌐 It accepts common flags.

常见标志

🌐 Common flags

--dir

供应型号： dev、build、lint、migrate

到你的 Mastra 文件夹的路径。默认值为 src/mastra。

🌐 The path to your Mastra folder. Defaults to src/mastra.

--debug

可用于： dev、build、migrate

为 Mastra 的内部启用详细日志记录。默认值为 false。

🌐 Enable verbose logging for Mastra's internals. Defaults to false.

--env

供应型号： dev、start、studio、migrate

要包含的自定义环境变量文件。默认情况下，包括 .env.development、.env.local 和 .env。

🌐 Custom environment variables file to include. By default, includes .env.development, .env.local, and .env.

--root

供应型号： dev、build、lint、migrate

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

🌐 Path to your root folder. Defaults to process.cwd().

--tools

可用于： dev、build、lint

要包含的工具路径的逗号分隔列表。默认值为 src/mastra/tools。

🌐 Comma-separated list of tool paths to include. Defaults to src/mastra/tools.

全局标志

🌐 Global flags

使用这些标志来获取有关 mastra CLI 的信息。

🌐 Use these flags to get information about the mastra CLI.

--version

打印 Mastra CLI 版本并退出。

🌐 Prints the Mastra CLI version and exits.

--help

打印帮助信息并退出。

🌐 Prints help message and exits.

遥测

🌐 Telemetry

默认情况下，Mastra 会收集有关你的项目的匿名信息，如你的操作系统、Mastra 版本或 Node.js 版本。你可以查看 源代码 来了解收集了哪些信息。

🌐 By default, Mastra collects anonymous information about your project like your OS, Mastra version or Node.js version. You can read the source code to check what's collected.

你可以通过设置环境变量来选择退出 CLI 分析：

🌐 You can opt out of the CLI analytics by setting an environment variable:

MASTRA_TELEMETRY_DISABLED=1

你也可以在使用其他 mastra 命令时设置这个：

🌐 You can also set this while using other mastra commands:

MASTRA_TELEMETRY_DISABLED=1 mastra dev