Mastra CLI

1.6.0 · active · verified Sat Apr 18

The `mastra` package provides the command-line interface (CLI) for the Mastra AI platform, enabling development, deployment, and management of AI agents, LLMs, and related services. It is currently at version 1.6.0. While the CLI itself might have a slower release pace, its core library (`@mastra/core`), which it depends on, is under active and rapid development, seeing multiple releases per month, indicating a quickly evolving ecosystem of features.

Common errors

```
mastra: command not found
```
cause The `mastra` package's executable is not in your system's PATH, or the package was not installed globally/linked correctly.

fix If installed locally, run `npx mastra <command>`. If you intended a global install, run `npm install -g mastra` and ensure your global `node_modules` bin directory is in your PATH.
```
Error: Peer dependency "@mastra/core" is not installed or incompatible. Expected ">=1.1.0-0 <2.0.0-0".
```
cause The `@mastra/core` package, a required peer dependency for `mastra`, is either missing or its installed version does not meet the compatibility requirements.

fix Run `npm install @mastra/core@'>=1.1.0-0 <2.0.0-0'` in your project to install a compatible version.
```
Error: Zod peer dependency not found. Please install zod@^3.25.0 || ^4.0.0.
```
cause The `zod` validation library, a peer dependency, is not installed or its version is outside the supported range.

fix Run `npm install zod@'^3.25.0 || ^4.0.0'` in your project.
```
Error: RAG tracing requires an 'observabilityContext'. Please configure one.
```
cause You are attempting to use RAG tracing features without providing the necessary `observabilityContext` for instrumentation.

fix Ensure you initialize and pass an `observabilityContext` to the relevant RAG ingestion or query operations where tracing is desired.
```
Error: Workspace path '/absolute/path/to/file.txt' is no longer treated as workspace-relative. Use relative paths or verify the absolute path's intent.
```
cause Your workspace configuration or a tool within the workspace is using an absolute path (`/absolute/path/to/file.txt`) which is no longer interpreted relative to the workspace root after a breaking change in `@mastra/core` v1.12.0.

fix Update your workspace configuration to use paths relative to the workspace root for internal files, or explicitly manage absolute paths if they refer to external locations.

Warnings

gotcha The `mastra` CLI has a peer dependency on `zod` and `@mastra/core`. Ensure these are installed and compatible with your project.
Fix: npm install zod@'^3.25.0 || ^4.0.0' @mastra/core@'>=1.1.0-0 <2.0.0-0'
breaking Workspace filesystem path resolution now aligns with standard filesystem semantics. Absolute paths like `/file.txt` are no longer treated as workspace-relative but resolve to actual file system locations.
Fix: Review existing workspace configurations that use absolute paths. Adjust them to be relative to the workspace root or ensure they correctly point to external absolute paths.
gotcha End-to-end RAG tracing and new RAG/Graph span types (e.g., `RAG_INGESTION`) are opt-in and require an `observabilityContext` to be explicitly configured.
Fix: Pass an `observabilityContext` to relevant Mastra operations to enable tracing for RAG and graph interactions.
gotcha Workspace tool output is now token-limited and ANSI-stripped for model context. This might affect applications that relied on full, unstripped terminal output from sandbox commands.
Fix: If full or ANSI-formatted output is required for external processing, consider using direct system commands or adapting your parsing logic to the new token-limited and stripped format.
deprecated The peer dependency `@mastra/core` is constrained to versions `>=1.1.0-0 <2.0.0-0`. Major version 2 of `@mastra/core` will likely introduce breaking changes and require an update to the `mastra` CLI.
Fix: Monitor for future releases of `mastra` CLI that declare compatibility with `@mastra/core` v2. Plan for an upgrade when `@mastra/core` v2 is released.

Install

npm install mastra npm
yarn add mastra yarn
pnpm add mastra pnpm

Imports

run
```
import { run } from 'mastra'
```
Primarily a CLI tool, programmatic imports are less common but may expose a 'run' function for advanced use cases.

Quickstart

Demonstrates initializing an agent with @mastra/core and how to use the 'mastra' CLI to deploy it. Note: replace 'gpt-4o' with a valid model.

import { Agent } from '@mastra/core';

const agent = new Agent({ name: 'MyFirstAgent', model: 'gpt-4o' });

// To run a command via the CLI (most common usage):
// npx mastra deploy MyFirstAgent --env production

view raw JSON →