Mastra CLI 完全指南初始化、开发、构建、部署与运维一条龙实战【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastraMastra 是一个基于现代 TypeScript 技术栈构建 AI 应用与 Agent 的框架而mastra包正是其官方命令行工具CLI。本文将围绕 packages/cli/README.md 展开结合仓库源码逐一拆解 CLI 的安装方式、全部核心命令及其参数覆盖从初始化项目、本地开发调试、生产构建、启动应用、部署上线、环境变量管理、数据库迁移到评估评分器的完整生命周期帮助你从零上手并系统掌握 Mastra CLI 的实战用法。Mastra CLI 是什么从 package.json 的bin字段可以看到mastra包暴露了名为mastra的可执行命令指向dist/index.jsCLI 本体要求 Node.js 22.13.0并以commander作为命令解析框架。其职责官方定位为初始化项目、运行本地开发服务器与 Studio、构建生产产物、启动构建后的应用、部署受支持的项目、管理环境变量、执行数据库迁移以及与评估evaluations和评分器scorers协作。从 命令行入口文件 可以清晰看到整套命令的注册结构create、init、lint、dev、build、experiment、worker、start、deploy、studio、migrate、scorers、auth、env、server等构成了 CLI 的完整能力矩阵。安装 CLICLI 提供三种安装方式适用于不同场景1. 全局安装推荐任意目录可用npm install --global mastra2. 免安装直接运行借助 npxnpx mastra --help这种方式不需要全局安装临时查看帮助或跑一次性命令时很方便。3. 项目本地安装npm install mastra本地安装适合团队协作时锁定 CLI 版本。注意 CLI 的peerDependencies声明了对mastra/core的依赖版本范围为1.50.0-0 2.0.0-0使用前请确保项目中的核心包版本匹配。快速开始从零搭建一个 Mastra 项目使用 create-mastra 脚手架新建项目README 推荐通过create-mastra一步到位地生成新应用npx create-mastralatest从 create 命令实现 可以看到create支持三种模式managed默认托管模式交互式引导你输入项目名、选择默认模型提供商OpenAI、Anthropic 等、录入 API Key并询问是否开启平台可观测性Observability随后克隆官方默认模板template-agent-harnessAgent Harness并根据所选提供商改写配置empty空项目模式仅生成最小骨架不克隆任何模板template模板模式从内置模板列表中挑选如mastra create --template slug甚至可以直接传入一个 GitHub 仓库地址https://github.com/owner/repository。值得一提的是create对 GitHub 模板仓库有自动校验逻辑会抓取远端package.json检查是否声明了mastra/core依赖并检查src/mastra/index.ts是否存在且导出了Mastra实例校验失败会明确报错避免拉取到不合格的模板。创建完成后 CLI 还会自动执行git init默认开启可用--no-git关闭并尝试为 Claude Code、Codex、Cursor 等编码 Agent 安装 Mastra Skills可用--no-skills关闭。在已有 TypeScript 项目中初始化如果你的项目已存在只想在其中加入 Mastra使用mastra initmastra initinit子命令注册定义见 入口文件支持以下常用参数参数说明--default使用默认配置快速开始src 目录、OpenAI、示例代码-d, --dir directoryMastra 文件存放目录默认src/-c, --components components逗号分隔的组件列表agents、workflows、scorers 等-l, --llm model-provider默认模型提供商-k, --llm-api-key api-key模型提供商的 API Key-e, --example包含示例代码-n, --no-example不包含示例代码-m, --mcp editor为代码编辑器安装 MCP Servercursor、cursor-global、windsurf、vscode、antigravity--observability/--no-observability启用/禁用 Mastra 可观测性--observability-project name关联或新建平台项目用于可观测性从 init 实现 看初始化时会创建 Mastra 目录、写入index.ts入口根据所选组件决定是否包含 agents、workflows、scorers、写入 API Key 到.env。如果开启了--example还会按需自动安装mastra/libsql、mastra/duckdb、mastra/memory、mastra/loggers、mastra/observability、mastra/evals等配套依赖。若选择了 skills 或 MCP 编辑器则会额外生成AGENTS.md选择 Claude Code 时还会生成CLAUDE.md供编码 Agent 参考。核心工作流dev / build / startREADME 给出的最基础三条命令即构成了日常开发循环mastra dev mastra build mastra start本地开发服务器mastra devdev启动本地开发服务器默认端口 4111支持热更新与调试。常用参数参数说明-d, --dir dirMastra 目录路径-r, --root root项目根目录路径monorepo 场景用-t, --tools toolsDirs逗号分隔的工具文件路径列表-e, --env env自定义 env 文件-i, --inspect [host:port]以 inspect 模式启动如0.0.0.0:9229-b, --inspect-brk [host:port]inspect 模式并在脚本开头断点-c, --custom-args args传给开发服务器的自定义 Node 参数如--experimental-transform-types-s, --https启用本地 HTTPS--request-context-presets filerequest context presets JSON 文件路径--debug开启调试日志此外还有一个mastra factory dev子命令与dev参数完全一致用于开发 Mastra Factory 相关应用参见 入口文件。生产构建mastra buildbuild将项目打包为可直接运行的生产产物默认输出到.mastra/output参数包括-d, --dir pathMastra 目录路径-r, --root path项目根目录-t, --tools toolsDirs工具文件路径列表-s, --studio将 Studio UI 一并打包进构建产物-f, --force即使当前目录有mastra dev在运行也强制构建--debug开启调试日志启动构建产物mastra startstart运行已构建的应用-d, --dir path构建产物目录默认.mastra/output-e, --env env启动时加载的自定义 env 文件-c, --custom-args args传给 Node.js 进程的自定义参数例如--requirenewrelic独立 Worker 的构建与运行对于需要独立部署后台任务/Worker 的场景CLI 提供了一组worker命令# 打包 worker默认输出 .mastra/output/index.mjs mastra worker build # 启动构建好的 worker可用 [name] 设置 MASTRA_WORKERS mastra worker start [name] # 构建并启动一步到位 mastra worker dev [name]worker build支持-o, --output-dir指定输出目录——当与服务器产物同目录时会互相覆盖适合拆分部署时传入不同路径让两者共存。experiment build命令则用于构建独立的实验 worker默认输出.mastra/experiment-worker。部署与运维统一部署命令mastra deploymastra deploy [dir] --env productiondeploy是面向环境的统一部署入口支持参数--env name目标环境默认production--org id/--project id指定组织与项目project 不存在时会自动创建-y, --yes跳过确认自动接受默认值适合 CI-c, --config file项目配置文件路径默认.mastra-project.json--env-file file要部署的 env 文件如.env.production--skip-build跳过构建复用已有.mastra/output--skip-preflight跳过部署前的构建/环境校验--region region新环境所在区域如us、eu--workers mode后台 Worker 部署模式dedicated独立 Worker 服务推荐需要 Redis或in-process后台任务跑在 API 服务器容器内Studio 管理与部署mastra studio用于管理 Mastra Studio可视化调试界面可通过-p, --port默认 3000、-s, --server-port默认 4111、-x, --server-protocol默认 http等参数指定连接方式。Studio 也支持直接部署mastra studio deploy [dir] mastra studio deploy list mastra studio deploy status deploy-id # 加 -w 可监听状态变化 mastra studio deploy logs deploy-id # 加 -f 实时流式查看日志 mastra studio projects createMastra Server 管理mastra server系列命令用于管理 Mastra Server 上的托管部署server deploy部署、server pause暂停实例、server restart重启实例以及server env下的list / set / unset / import / pull环境变量操作。多数命令支持-c, --config指定配置文件并遵循MASTRA_PROJECT_ID环境变量作为项目关联。环境变量与凭据管理本地环境变量env命令组由 env/index.ts 注册负责本地 env 文件的读写管理其中env db子命令用于管理数据库相关配置。服务端环境变量mastra server env系列支持mastra server env list mastra server env set key value mastra server env unset key mastra server env import file mastra server env pull [file] # 拉取项目级变量到本地 .env账号认证mastra auth命令组提供login、logout、whoami、orgs switch、tokens create/revoke等能力用于登录 Mastra 平台、切换组织和管理 API Token是执行部署类命令的前提。数据库迁移mastra migrate当存储结构发生变化时运行迁移命令更新 schemamastra migrate支持的参数包括-d, --dirMastra 目录、-r, --root项目根目录、-e, --env自定义 env 文件、-y, --yes跳过确认面向 CI/自动化。从 迁移实现 可以看到命令会自动探测入口文件src/mastra/index.ts或index.js找不到时会给出明确提示在 monorepo 中可显式指定npx mastra migrate --dir path/to/src/mastra --root path/to/project-root代码质量检查mastra lintlint用于检查 Mastra 项目配置是否规范mastra lint -d path -r path关键参数--preflight同时执行 bundle 预检必要时先构建--skip-build跳过构建、复用已有.mastra/output需配合--preflight--env-file file预检用的 env 文件需配合--preflight--strict将警告视为错误--json输出机器可读的 JSON--debug开启调试日志评估与评分器mastra scorers针对 AI 输出的评估场景CLI 提供评分器管理mastra scorers add [scorer-name] # 向项目新增一个评分器 mastra scorers list # 列出可用评分器模板add支持-d, --dir指定 Mastra 目录默认自动探测。这为基于 evals 的自动化评估工作流提供了脚手架能力可与 packages/evals 包配合使用。源码视角CLI 是如何组织起来的理解 CLI 的源码结构有助于你预测命令行为与排查问题入口与命令注册packages/cli/src/index.ts 是命令注册总表每个命令通过program.command(...)定义参数经由commander的.option()声明并绑定到对应的 action 实现它还初始化了基于 Posthog 的匿名使用分析可通过MASTRA_ANALYTICS_ORIGIN环境变量标记来源。命令实现分层每个子命令的 action 都拆分为独立的模块如 dev、build、start 等action 薄壳负责参数转换与埋点核心逻辑在底层模块中便于测试。完整的测试覆盖仓库为几乎所有命令配备了单元测试例如 dev.test.ts、start.test.ts、create.test.ts可作为了解各命令行为的权威参考。版本与更新CLI 的版本演进与发布说明记录在 packages/cli/CHANGELOG.md升级前建议先查看变更内容。通过mastra --version或mastra -v可随时查看当前 CLI 版本。小结Mastra CLI 覆盖了一个 AI 应用从诞生到上线的完整生命周期create/init负责项目搭建dev Studio 负责本地开发调试build/start/worker负责产物构建与运行deploy/server/studio deploy负责多环境部署env/auth/migrate负责配置与数据管理lint/scorers则护航代码质量与评估体系。结合 packages/cli/src 下的源码与测试你可以在排查问题时快速定位到具体命令的底层实现让 CLI 真正成为你驾驭 Mastra 框架的得力工具。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Mastra CLI 完全指南：初始化、开发、构建、部署与运维一条龙实战
Mastra CLI 完全指南初始化、开发、构建、部署与运维一条龙实战【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastraMastra 是一个基于现代 TypeScript 技术栈构建 AI 应用与 Agent 的框架而mastra包正是其官方命令行工具CLI。本文将围绕 packages/cli/README.md 展开结合仓库源码逐一拆解 CLI 的安装方式、全部核心命令及其参数覆盖从初始化项目、本地开发调试、生产构建、启动应用、部署上线、环境变量管理、数据库迁移到评估评分器的完整生命周期帮助你从零上手并系统掌握 Mastra CLI 的实战用法。Mastra CLI 是什么从 package.json 的bin字段可以看到mastra包暴露了名为mastra的可执行命令指向dist/index.jsCLI 本体要求 Node.js 22.13.0并以commander作为命令解析框架。其职责官方定位为初始化项目、运行本地开发服务器与 Studio、构建生产产物、启动构建后的应用、部署受支持的项目、管理环境变量、执行数据库迁移以及与评估evaluations和评分器scorers协作。从 命令行入口文件 可以清晰看到整套命令的注册结构create、init、lint、dev、build、experiment、worker、start、deploy、studio、migrate、scorers、auth、env、server等构成了 CLI 的完整能力矩阵。安装 CLICLI 提供三种安装方式适用于不同场景1. 全局安装推荐任意目录可用npm install --global mastra2. 免安装直接运行借助 npxnpx mastra --help这种方式不需要全局安装临时查看帮助或跑一次性命令时很方便。3. 项目本地安装npm install mastra本地安装适合团队协作时锁定 CLI 版本。注意 CLI 的peerDependencies声明了对mastra/core的依赖版本范围为1.50.0-0 2.0.0-0使用前请确保项目中的核心包版本匹配。快速开始从零搭建一个 Mastra 项目使用 create-mastra 脚手架新建项目README 推荐通过create-mastra一步到位地生成新应用npx create-mastralatest从 create 命令实现 可以看到create支持三种模式managed默认托管模式交互式引导你输入项目名、选择默认模型提供商OpenAI、Anthropic 等、录入 API Key并询问是否开启平台可观测性Observability随后克隆官方默认模板template-agent-harnessAgent Harness并根据所选提供商改写配置empty空项目模式仅生成最小骨架不克隆任何模板template模板模式从内置模板列表中挑选如mastra create --template slug甚至可以直接传入一个 GitHub 仓库地址https://github.com/owner/repository。值得一提的是create对 GitHub 模板仓库有自动校验逻辑会抓取远端package.json检查是否声明了mastra/core依赖并检查src/mastra/index.ts是否存在且导出了Mastra实例校验失败会明确报错避免拉取到不合格的模板。创建完成后 CLI 还会自动执行git init默认开启可用--no-git关闭并尝试为 Claude Code、Codex、Cursor 等编码 Agent 安装 Mastra Skills可用--no-skills关闭。在已有 TypeScript 项目中初始化如果你的项目已存在只想在其中加入 Mastra使用mastra initmastra initinit子命令注册定义见 入口文件支持以下常用参数参数说明--default使用默认配置快速开始src 目录、OpenAI、示例代码-d, --dir directoryMastra 文件存放目录默认src/-c, --components components逗号分隔的组件列表agents、workflows、scorers 等-l, --llm model-provider默认模型提供商-k, --llm-api-key api-key模型提供商的 API Key-e, --example包含示例代码-n, --no-example不包含示例代码-m, --mcp editor为代码编辑器安装 MCP Servercursor、cursor-global、windsurf、vscode、antigravity--observability/--no-observability启用/禁用 Mastra 可观测性--observability-project name关联或新建平台项目用于可观测性从 init 实现 看初始化时会创建 Mastra 目录、写入index.ts入口根据所选组件决定是否包含 agents、workflows、scorers、写入 API Key 到.env。如果开启了--example还会按需自动安装mastra/libsql、mastra/duckdb、mastra/memory、mastra/loggers、mastra/observability、mastra/evals等配套依赖。若选择了 skills 或 MCP 编辑器则会额外生成AGENTS.md选择 Claude Code 时还会生成CLAUDE.md供编码 Agent 参考。核心工作流dev / build / startREADME 给出的最基础三条命令即构成了日常开发循环mastra dev mastra build mastra start本地开发服务器mastra devdev启动本地开发服务器默认端口 4111支持热更新与调试。常用参数参数说明-d, --dir dirMastra 目录路径-r, --root root项目根目录路径monorepo 场景用-t, --tools toolsDirs逗号分隔的工具文件路径列表-e, --env env自定义 env 文件-i, --inspect [host:port]以 inspect 模式启动如0.0.0.0:9229-b, --inspect-brk [host:port]inspect 模式并在脚本开头断点-c, --custom-args args传给开发服务器的自定义 Node 参数如--experimental-transform-types-s, --https启用本地 HTTPS--request-context-presets filerequest context presets JSON 文件路径--debug开启调试日志此外还有一个mastra factory dev子命令与dev参数完全一致用于开发 Mastra Factory 相关应用参见 入口文件。生产构建mastra buildbuild将项目打包为可直接运行的生产产物默认输出到.mastra/output参数包括-d, --dir pathMastra 目录路径-r, --root path项目根目录-t, --tools toolsDirs工具文件路径列表-s, --studio将 Studio UI 一并打包进构建产物-f, --force即使当前目录有mastra dev在运行也强制构建--debug开启调试日志启动构建产物mastra startstart运行已构建的应用-d, --dir path构建产物目录默认.mastra/output-e, --env env启动时加载的自定义 env 文件-c, --custom-args args传给 Node.js 进程的自定义参数例如--requirenewrelic独立 Worker 的构建与运行对于需要独立部署后台任务/Worker 的场景CLI 提供了一组worker命令# 打包 worker默认输出 .mastra/output/index.mjs mastra worker build # 启动构建好的 worker可用 [name] 设置 MASTRA_WORKERS mastra worker start [name] # 构建并启动一步到位 mastra worker dev [name]worker build支持-o, --output-dir指定输出目录——当与服务器产物同目录时会互相覆盖适合拆分部署时传入不同路径让两者共存。experiment build命令则用于构建独立的实验 worker默认输出.mastra/experiment-worker。部署与运维统一部署命令mastra deploymastra deploy [dir] --env productiondeploy是面向环境的统一部署入口支持参数--env name目标环境默认production--org id/--project id指定组织与项目project 不存在时会自动创建-y, --yes跳过确认自动接受默认值适合 CI-c, --config file项目配置文件路径默认.mastra-project.json--env-file file要部署的 env 文件如.env.production--skip-build跳过构建复用已有.mastra/output--skip-preflight跳过部署前的构建/环境校验--region region新环境所在区域如us、eu--workers mode后台 Worker 部署模式dedicated独立 Worker 服务推荐需要 Redis或in-process后台任务跑在 API 服务器容器内Studio 管理与部署mastra studio用于管理 Mastra Studio可视化调试界面可通过-p, --port默认 3000、-s, --server-port默认 4111、-x, --server-protocol默认 http等参数指定连接方式。Studio 也支持直接部署mastra studio deploy [dir] mastra studio deploy list mastra studio deploy status deploy-id # 加 -w 可监听状态变化 mastra studio deploy logs deploy-id # 加 -f 实时流式查看日志 mastra studio projects createMastra Server 管理mastra server系列命令用于管理 Mastra Server 上的托管部署server deploy部署、server pause暂停实例、server restart重启实例以及server env下的list / set / unset / import / pull环境变量操作。多数命令支持-c, --config指定配置文件并遵循MASTRA_PROJECT_ID环境变量作为项目关联。环境变量与凭据管理本地环境变量env命令组由 env/index.ts 注册负责本地 env 文件的读写管理其中env db子命令用于管理数据库相关配置。服务端环境变量mastra server env系列支持mastra server env list mastra server env set key value mastra server env unset key mastra server env import file mastra server env pull [file] # 拉取项目级变量到本地 .env账号认证mastra auth命令组提供login、logout、whoami、orgs switch、tokens create/revoke等能力用于登录 Mastra 平台、切换组织和管理 API Token是执行部署类命令的前提。数据库迁移mastra migrate当存储结构发生变化时运行迁移命令更新 schemamastra migrate支持的参数包括-d, --dirMastra 目录、-r, --root项目根目录、-e, --env自定义 env 文件、-y, --yes跳过确认面向 CI/自动化。从 迁移实现 可以看到命令会自动探测入口文件src/mastra/index.ts或index.js找不到时会给出明确提示在 monorepo 中可显式指定npx mastra migrate --dir path/to/src/mastra --root path/to/project-root代码质量检查mastra lintlint用于检查 Mastra 项目配置是否规范mastra lint -d path -r path关键参数--preflight同时执行 bundle 预检必要时先构建--skip-build跳过构建、复用已有.mastra/output需配合--preflight--env-file file预检用的 env 文件需配合--preflight--strict将警告视为错误--json输出机器可读的 JSON--debug开启调试日志评估与评分器mastra scorers针对 AI 输出的评估场景CLI 提供评分器管理mastra scorers add [scorer-name] # 向项目新增一个评分器 mastra scorers list # 列出可用评分器模板add支持-d, --dir指定 Mastra 目录默认自动探测。这为基于 evals 的自动化评估工作流提供了脚手架能力可与 packages/evals 包配合使用。源码视角CLI 是如何组织起来的理解 CLI 的源码结构有助于你预测命令行为与排查问题入口与命令注册packages/cli/src/index.ts 是命令注册总表每个命令通过program.command(...)定义参数经由commander的.option()声明并绑定到对应的 action 实现它还初始化了基于 Posthog 的匿名使用分析可通过MASTRA_ANALYTICS_ORIGIN环境变量标记来源。命令实现分层每个子命令的 action 都拆分为独立的模块如 dev、build、start 等action 薄壳负责参数转换与埋点核心逻辑在底层模块中便于测试。完整的测试覆盖仓库为几乎所有命令配备了单元测试例如 dev.test.ts、start.test.ts、create.test.ts可作为了解各命令行为的权威参考。版本与更新CLI 的版本演进与发布说明记录在 packages/cli/CHANGELOG.md升级前建议先查看变更内容。通过mastra --version或mastra -v可随时查看当前 CLI 版本。小结Mastra CLI 覆盖了一个 AI 应用从诞生到上线的完整生命周期create/init负责项目搭建dev Studio 负责本地开发调试build/start/worker负责产物构建与运行deploy/server/studio deploy负责多环境部署env/auth/migrate负责配置与数据管理lint/scorers则护航代码质量与评估体系。结合 packages/cli/src 下的源码与测试你可以在排查问题时快速定位到具体命令的底层实现让 CLI 真正成为你驾驭 Mastra 框架的得力工具。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
