CLI commands

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

mastra dev

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

Enable local HTTPS support. Learn more.

--inspect

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

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

Comma-separated list of custom arguments to pass to the Node.js process, e.g. --require=newrelic or --experimental-transform-types.

--request-context-presets

Path to a JSON file containing named request context presets. When provided, a dropdown displays in Studio's request context editor, letting you quickly switch between preset configurations.

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

The file must be a JSON object where each key is a preset name and each value is an object:

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

Configs

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

Skip peer dependency check

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 aren't yet published.

Disable build caching

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 caps how many expensive operations run in parallel (primarily build and evaluation steps). For example:

MASTRA_CONCURRENCY=4 mastra dev

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

Custom provider endpoints

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

For Anthropic:

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

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

mastra build

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 straightforward to deploy Mastra agents as HTTP endpoints with middleware support.

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.

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

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

Bundle the Studio UI with the build.

Configs

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

Skip peer dependency check

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

MASTRA_SKIP_PEERDEP_CHECK=1 mastra build

Limit parallelism

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

You need to run mastra build before using mastra start.

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

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

--custom-args

Comma-separated list of custom arguments to pass to the Node.js process, e.g. --require=newrelic or --experimental-transform-types.

mastra studio

Starts 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. Looks for .env and .env.production files in the current working directory for configuration.

Flags

The command accepts common flags and the following additional flags:

--port

The port to run Studio on. Defaults to 3000.

--server-host

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

--server-port

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

--server-protocol

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

--server-api-prefix

The API route prefix of the Mastra API server. Defaults to /api.

--request-context-presets

Path to a JSON file containing named request context presets. Works the same as the mastra dev flag.

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

mastra studio deploy

Builds and deploys your project to Mastra platform. Requires authentication via mastra auth login or a MASTRA_API_TOKEN environment variable.

mastra studio deploy

The command runs mastra build, zips the output, reads environment variables from .env, .env.local, and .env.production, and uploads everything to the platform. After uploading, it polls the deploy status and streams build logs until the deploy reaches a terminal state.

Organization and project are resolved in order from: Environment variable flag, .mastra-project.json config file, current org from credentials, and lastly interactive prompt. On first deploy, the CLI saves the resolved IDs to .mastra-project.json so subsequent deploys skip the prompts.

Arguments

[dir]

Project directory. Defaults to the current directory.

Flags

--org

Organization ID. Can also be set via the MASTRA_ORG_ID environment variable.

--project

Project ID or slug. Can also be set via the MASTRA_PROJECT_ID environment variable.

-y, --yes

Auto-accept defaults without confirmation prompts.

-c, --config

Path to the project config file. Defaults to .mastra-project.json.

--skip-build

Skip the build step and deploy the existing .mastra/output directory.

--debug

Enable debug logs during the build step.

CI/CD usage

Set MASTRA_API_TOKEN, MASTRA_ORG_ID, and MASTRA_PROJECT_ID as environment variables for headless deploys. Interactive prompts are skipped automatically when MASTRA_API_TOKEN is set.

mastra studio deploy list

Lists all projects with their latest deploy status and URL.

mastra studio deploy status

Shows the status of a specific deploy.

mastra studio deploy status <deploy-id>

--watch, -w

Poll for status changes until the deploy reaches a terminal state.

mastra studio deploy logs

Shows logs for a specific deploy.

mastra studio deploy logs <deploy-id>

--follow, -f

Stream logs in real time.

--tail

Number of recent log lines to show.

mastra studio projects

Lists all projects in the current organization.

mastra studio projects create

Creates a new project through an interactive prompt.

mastra server deploy

Builds and deploys your project to Server on Mastra platform. Works the same as mastra studio deploy with the same flags, arguments, and resolution logic.

mastra server deploy [dir]

mastra server pause

Pauses the running server instance for the linked project. Organization and project resolution work the same as mastra server deploy.

mastra server pause

Flags

--org

Organization ID. Can also be set via the MASTRA_ORG_ID environment variable.

--project

Project ID or slug when MASTRA_PROJECT_ID is not set. Slugs are resolved against projects in the current organization.

-c, --config

Path to the project config file. Defaults to .mastra-project.json.

Fails if the instance is not running.

mastra server restart

Restarts a paused or stopped server instance for the linked project. After the platform accepts the restart, the CLI resolves the deploy id (from the API response or by polling project and deploy metadata when the response omits an id), then streams build and deploy logs the same way as mastra server deploy until the deploy reaches a terminal state.

Flags

Same flags as mastra server pause: --org, --project, and -c / --config, with the same defaults and behavior.

mastra server restart

Fails if a deployment is still active for this project (running, building, deploying, etc.); that is a platform restriction so you cannot restart while another deploy is in progress.

mastra server env

Manages environment variables for the linked server deployment. Organization and project resolution work the same as mastra server deploy.

Every subcommand accepts -c / --config for the project config file path (defaults to .mastra-project.json).

mastra server env list

Lists all environment variables for the linked project. Values are partially masked in the output.

mastra server env set

Sets an environment variable. The CLI reads the current map, applies the change, and uploads the result.

mastra server env set <key> <value>

mastra server env unset

Removes an environment variable.

mastra server env unset <key>

mastra server env import

Imports variables from a file (for example a .env file) and merges them into the existing map. New values override keys that already exist on the server.

mastra server env import <file>

mastra server env pull

Downloads environment variables from the linked project and writes them to a local file. This is the inverse of mastra server env import.

mastra server env pull [file]

The file defaults to .env when no argument is given. All values are double-quoted and escaped for safe shell sourcing. Keys that aren't valid shell identifiers are skipped. The output file is created with restrictive permissions (0600) since it contains secrets.

--project

Project ID or slug. Overrides the linked project when MASTRA_PROJECT_ID isn't set.

CI usage

In a continuous-integration pipeline, authenticate with MASTRA_API_TOKEN and pull the environment before running your app:

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

mastra auth

Manages authentication for Mastra platform. Credentials are stored in ~/.mastra/credentials.json. You can also set the MASTRA_API_TOKEN environment variable as an alternative to interactive login.

mastra auth login

Opens a browser for login and stores the credentials locally.

mastra auth logout

Removes stored credentials. If MASTRA_API_TOKEN is still set in the environment, the CLI warns that it will continue to be used.

mastra auth whoami

Shows the current user email, user ID, and active organization.

mastra auth orgs

Lists all organizations with your role in each. The current organization is marked.

mastra auth orgs switch

Switches the active organization through an interactive prompt. Cannot be used when MASTRA_API_TOKEN or MASTRA_ORG_ID environment variables are set.

mastra auth tokens

Lists all API tokens with their last-used date.

mastra auth tokens create

Creates a new API token. The secret is displayed once and cannot be retrieved again.

mastra auth tokens create <name>

mastra auth tokens revoke

Revokes an API token.

mastra auth tokens revoke <token-id>

mastra lint

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

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

Use the list command to get the correct ID.

list

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

mastra init

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

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

--dir

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

--components

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

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

--llm-api-key

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

Don't include example code. Useful when using the --default flag.

--mcp

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

mastra migrate

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:

• Duplicate spans migration: Removes duplicate (traceId, spanId) entries and adds a unique constraint to ensure data integrity.

mastra migrate

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

It accepts common flags.

Common flags

--dir

Available in: dev, build, lint, migrate

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

--debug

Available in: dev, build, migrate

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

--env

Available in: dev, start, studio, migrate

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

--root

Available in: dev, build, lint, migrate

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

--tools

Available in: dev, build, lint

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

Global flags

Use these flags to get information about the mastra CLI.

--version

Prints the Mastra CLI version and exits.

--help

Prints help message and exits.

Telemetry

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.

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

MASTRA_TELEMETRY_DISABLED=1

You can also set this while using other mastra commands:

MASTRA_TELEMETRY_DISABLED=1 mastra dev