# 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](https://mastra.ai/docs/studio/overview) 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](https://mastra.ai/reference/configuration).

### Flags

The command accepts [common flags](#common-flags) and the following additional flags:

#### `--https`

Enable local HTTPS support. [Learn more](https://mastra.ai/reference/configuration).

#### `--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](https://mastra.ai/docs/server/request-context) presets. When provided, a dropdown displays in Studio's request context editor, letting you quickly switch between preset configurations.

```bash
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:

```json
{
  "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:

```bash
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/`:

```bash
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:

```bash
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:

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

For Anthropic:

```bash
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](https://hono.dev/) 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`](#mastra-start).

If you're deploying to a [serverless platform](https://mastra.ai/docs/deployment/cloud-providers) you need to install the correct deployer in order to receive the correct output in `.mastra`.

It accepts [common flags](#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:

```bash
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`.

```bash
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](https://mastra.ai/docs/observability/tracing/overview) is enabled.

### Flags

The command accepts [common flags](#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](https://mastra.ai/docs/studio/overview) 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](#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](https://mastra.ai/docs/server/request-context) presets. Works the same as the [`mastra dev` flag](#--request-context-presets).

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

## `mastra studio deploy`

Builds and deploys your project to Mastra platform. Requires authentication via [`mastra auth login`](#mastra-auth-login) or a `MASTRA_API_TOKEN` environment variable.

```bash
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 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>` does not 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:

```bash
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`).

```bash
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.

```bash
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.

```bash
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.

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

If you omit `deploy-id`, the command uses the latest deploy for the linked project. If a diagnosis does not 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 does not accept a `--name` flag; for non-interactive project creation, use [`mastra studio deploy --project <name> --yes`](#mastra-studio-deploy) 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`](#mastra-studio-deploy) with the same flags, arguments, and resolution logic.

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

### `mastra server deploy suggestions`

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

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

If you omit `deploy-id`, the command uses the latest deploy for the linked project. If a diagnosis does not 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-deploy).

```bash
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`](#mastra-server-deploy) until the deploy reaches a terminal state.

### Flags

Same flags as [`mastra server pause`](#mastra-server-pause): **`--org`**, **`--project`**, and **`-c` / `--config`**, with the same defaults and behavior.

```bash
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`](#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.

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

### `mastra server env unset`

Removes an environment variable.

```bash
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.

```bash
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-import).

```bash
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:

```bash
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.

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

#### `mastra auth tokens revoke`

Revokes an API token.

```bash
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](#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](https://mastra.ai/docs/evals/overview) to learn more.

### `add`

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

```bash
mastra scorers add
```

Or provide a scorer name directly:

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

Use the [`list`](#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.

```bash
mastra migrate
```

See the [Storage migration guide](https://mastra.ai/guides/migrations/upgrade-to-v1/storage) for details on when migrations are needed.

It accepts [common flags](#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](https://github.com/mastra-ai/mastra/blob/main/packages/cli/src/analytics/index.ts) to check what's collected.

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

```bash
MASTRA_TELEMETRY_DISABLED=1
```

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

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