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 an env file from the project directory, and uploads everything to the platform. After uploading, it polls the deploy status and streams build logs until the deploy reaches a terminal state.

The deploy command auto-loads the project's .env file. If MASTRA_PROJECT_ID points to a project that was provisioned for Observability, the deploy links to that project instead of creating a new one. Deploying Studio to an observability-only project converts it into a Studio project on the platform side.

The CLI requires at least one .env or .env.* file (excluding .env.example) in the project directory and fails with Error: No env file found for deploy. if none exists. When multiple env files are present, the CLI prompts you to pick one (defaulting to .env.production); pass --env-file to choose explicitly. With --yes and multiple env files, you must pass --env-file or the deploy errors.

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.

If --project <value> doesn't match an existing project (by ID or slug), the CLI treats <value> as a new project name and creates it after confirmation. Combined with --yes, this creates and deploys a new project in one non-interactive command:

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

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. If no project matches, the value is used as the name of a new project to create on deploy.

-y, --yes

Auto-accept defaults without confirmation prompts.

-c, --config

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

--env-file

Path to the env file to bundle with the deploy (relative to the project directory). Use this to deploy the same project to multiple environments by pointing at different env files (for example .env.staging, .env.production).

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

--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 deploy suggestions

Shows diagnosis results and suggested fixes for a failed Studio deploy.

mastra studio deploy suggestions [deploy-id]

If you omit deploy-id, the command uses the latest deploy for the linked project. If a diagnosis doesn't exist yet, the command starts one and polls until results are ready. If the deploy is healthy, no suggestions are shown.

mastra studio projects

Lists all projects in the current organization.

mastra studio projects create

Creates a new project through an interactive prompt. This command doesn't accept a --name flag; for non-interactive project creation, use mastra studio deploy --project <name> --yes instead, which creates the project and deploys to it in one step.

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.

The deploy command auto-loads the project's .env file. If MASTRA_PROJECT_ID points to a project that was provisioned for Observability, the deploy links to that project instead of creating a new one. Deploying Server to an observability-only project converts it into a Server project on the platform side.

mastra server deploy [dir]

mastra server deploy suggestions

Shows diagnosis results and suggested fixes for a failed Server deploy.

mastra server deploy suggestions [deploy-id]

If you omit deploy-id, the command uses the latest deploy for the linked project. If a diagnosis doesn't exist yet, the command starts one and polls until results are ready. If the deploy is healthy, no suggestions are shown.

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 isn't 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 isn't 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's a platform restriction so you can't 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. Can't 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 can't 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.

By default, mastra lint runs project checks against your source files and configuration. Use --preflight to also run bundle checks against .mastra/output before deployment.

mastra lint --preflight

It accepts common flags.

Flags

--preflight

Runs deployment preflight checks against the built Mastra output. This builds the project before checking it unless you also pass --skip-build.

--skip-build

Skips the build step and reuses the existing .mastra/output directory. This flag only applies when --preflight is set.

--env-file <file>

Uses the specified environment file for preflight validation. This flag only applies when --preflight is set.

--strict

Treats warnings as errors.

--json

Emits machine-readable JSON output.

--debug

Enables debug logs.

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".

--observability

Enable Observability on the Mastra platform. The CLI prompts you to select an existing platform project or create a new one, writes the required environment variables, and configures the observability exporters.

--no-observability

Skip the Mastra Observability prompt.

--observability-project

Set the platform project name to use when Mastra Observability is enabled.

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.

mastra api

Calls a Mastra runtime server with JSON input and JSON output. Use it for local development servers, deployed Mastra platform projects, or self-hosted Mastra servers.

mastra api agent list --pretty
mastra api agent run weather-agent '{"messages":"What is the weather in London?"}'
mastra api tool execute get-weather '{"location":"San Francisco"}'

Use mastra api <resource> <action> --help to see examples for a command.

Output

Success responses are written to stdout as JSON. Single-resource commands return:

{ "data": {} }

List commands return a data array and pagination metadata:

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

Errors are written to stderr as JSON and return a non-zero exit code:

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

Target resolution

The command resolves the target server in this order:

1. --url <url> for an explicit remote or self-hosted server.
2. http://localhost:4111 for a local mastra dev server.
3. .mastra-project.json for a Mastra platform project.

Automatic platform auth is only used when the CLI resolves a Mastra platform target from .mastra-project.json. Localhost targets and explicit --url targets don't receive automatic credentials. Headers passed with --header are sent to any target, including localhost.

Flags

--url <url>

Target a specific Mastra server URL.

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

--header <"Key: Value">

Send a custom HTTP header. Repeat the flag to send multiple headers.

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

--timeout <ms>

Set the request timeout in milliseconds. Defaults to 30000. Workflow run start and resume commands default to 120000.

--pretty

Pretty-print JSON output. Defaults to false.

--schema

Print the CLI-oriented request schema for a command that accepts JSON input. The schema comes from the target server's route contracts and includes the command shape, positionals, examples, request schemas, and response shape.

--schema is available on leaf commands that accept JSON input. It isn't available as a top-level mastra api flag.

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

Input model

Commands that accept input take one inline JSON argument. Don't pass file paths or stdin.

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

Use positional arguments for stable IDs and JSON for filters or payloads. For routes that require both query parameters and a request body, pass one JSON object. The CLI splits the input according to the server route schema.

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

List commands accept page and perPage in the JSON input when the target route supports pagination:

mastra api score list '{"page":0,"perPage":50}'

Get command-specific help

Each mastra api leaf command includes command-specific examples in its help output. Use --help on the exact command you want to call:

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

Use --schema on commands that accept JSON input to inspect the request shape returned by the target server:

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

Some commands have important runtime requirements. For example, mastra api memory current update requires working memory to be enabled for the memory instance, and mastra api workflow run resume only works for suspended workflow runs.

Commands

mastra api agent list

Lists the agents registered on the target server. Pass optional JSON input for route-supported filters.

mastra api agent list [input]

mastra api agent get

Gets metadata for one registered agent.

mastra api agent get <agentId>

mastra api agent run

Runs an agent with JSON input. Use command help to see examples for text prompts, chat messages, and memory thread options.

mastra api agent run <agentId> <input>

mastra api workflow list

Lists workflows registered on the target server. Pass optional JSON input for route-supported filters.

mastra api workflow list [input]

mastra api workflow get

Gets metadata for one registered workflow.

mastra api workflow get <workflowId>

mastra api workflow run start

Starts a workflow run with JSON input. Workflow start commands use a longer default timeout than most commands because runs can take longer to complete.

mastra api workflow run start <workflowId> <input>

mastra api workflow run list

Lists runs for a workflow. Pass optional JSON input for route-supported filters or pagination.

mastra api workflow run list <workflowId> [input]

mastra api workflow run get

Gets one workflow run by ID.

mastra api workflow run get <workflowId> <runId>

mastra api workflow run resume

Resumes a suspended workflow run with JSON input. The run must be in a suspended state.

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

mastra api workflow run cancel

Cancels a workflow run.

mastra api workflow run cancel <workflowId> <runId>

mastra api tool list

Lists tools registered on the target server. Pass optional JSON input for route-supported filters.

mastra api tool list [input]

mastra api tool get

Gets metadata and schemas for one tool.

mastra api tool get <toolId>

mastra api tool execute

Executes a tool with JSON input. Raw tool input is wrapped as the route data field unless you pass an explicit data object.

mastra api tool execute <toolId> <input>

mastra api mcp list

Lists Model Context Protocol (MCP) servers registered on the target server. Pass optional JSON input for route-supported filters.

mastra api mcp list [input]

mastra api mcp get

Gets metadata for one MCP server.

mastra api mcp get <id>

mastra api mcp tool list

Lists tools exposed by an MCP server. Pass optional JSON input for route-supported filters.

mastra api mcp tool list <serverId> [input]

mastra api mcp tool get

Gets metadata and schemas for one MCP tool.

mastra api mcp tool get <serverId> <toolId>

mastra api mcp tool execute

Executes an MCP tool with JSON input. Raw tool input is wrapped as the route data field unless you pass an explicit data object.

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

mastra api thread list

Lists memory threads. Pass optional JSON input for route-supported filters.

mastra api thread list [input]

mastra api thread get

Gets one memory thread by ID.

mastra api thread get <threadId>

mastra api thread create

Creates a memory thread. Pass one JSON input object; the CLI splits fields such as agentId into query parameters when required by the server route.

mastra api thread create <input>

mastra api thread update

Updates a memory thread. Pass one JSON input object for fields such as agentId, resourceId, title, or metadata.

mastra api thread update <threadId> <input>

mastra api thread delete

Deletes a memory thread. Pass JSON input for route-required query parameters such as agentId and resourceId.

mastra api thread delete <threadId> <input>

mastra api thread messages

Lists messages for a memory thread. Pass optional JSON input for route-supported filters or pagination.

mastra api thread messages <threadId> [input]

mastra api memory search

Searches long-term memory. Use --help or --schema to inspect required fields such as agentId, resourceId, and searchQuery.

mastra api memory search <input>

mastra api memory current get

Reads current working memory for a thread.

mastra api memory current get <input>

mastra api memory current update

Updates current working memory for a thread. Working memory must be enabled for the memory instance.

mastra api memory current update <input>

mastra api memory status

Gets memory status for an agent and optional thread or resource context.

mastra api memory status <input>

mastra api trace list

Lists observability traces. Pass optional JSON input for route-supported filters or pagination.

mastra api trace list [input]

mastra api trace get

Gets one observability trace by ID.

mastra api trace get <traceId>

mastra api log list

Lists observability logs. Pass optional JSON input for route-supported filters or pagination.

mastra api log list [input]

mastra api score create

Creates an observability score. The input uses the server score body shape; inspect it with --schema.

mastra api score create <input>

mastra api score list

Lists observability scores. Pass optional JSON input for filters such as run ID or pagination.

mastra api score list [input]

mastra api score get

Gets one observability score by ID.

mastra api score get <scoreId>

mastra api dataset list

Lists datasets. Pass optional JSON input for route-supported filters or pagination.

mastra api dataset list [input]

mastra api dataset get

Gets one dataset by ID.

mastra api dataset get <datasetId>

mastra api dataset create

Creates a dataset with JSON input.

mastra api dataset create <input>

mastra api dataset items

Lists items in a dataset. Pass optional JSON input for route-supported filters or pagination.

mastra api dataset items <datasetId> [input]

mastra api experiment list

Lists experiments for a dataset. Pass optional JSON input for route-supported filters or pagination.

mastra api experiment list <datasetId> [input]

mastra api experiment get

Gets one experiment by ID.

mastra api experiment get <datasetId> <experimentId>

mastra api experiment run

Starts an experiment for a dataset with JSON input.

mastra api experiment run <datasetId> <input>

mastra api experiment results

Lists results for an experiment. Pass optional JSON input for route-supported filters or pagination.

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

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