{"id":14694,"library":"mastra","title":"Mastra CLI","description":"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.","status":"active","version":"1.6.0","language":"javascript","source_language":"en","source_url":"https://github.com/mastra-ai/mastra","tags":["javascript","mastra","cli","ai","llm","llms","agent","agents","dev","typescript"],"install":[{"cmd":"npm install mastra","lang":"bash","label":"npm"},{"cmd":"yarn add mastra","lang":"bash","label":"yarn"},{"cmd":"pnpm add mastra","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Primarily a CLI tool, programmatic imports are less common but may expose a 'run' function for advanced use cases.","symbol":"run","correct":"import { run } from 'mastra'"}],"quickstart":{"code":"import { Agent } from '@mastra/core';\n\nconst agent = new Agent({ name: 'MyFirstAgent', model: 'gpt-4o' });\n\n// To run a command via the CLI (most common usage):\n// npx mastra deploy MyFirstAgent --env production","lang":"typescript","description":"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."},"warnings":[{"fix":"npm install zod@'^3.25.0 || ^4.0.0' @mastra/core@'>=1.1.0-0 <2.0.0-0'","message":"The `mastra` CLI has a peer dependency on `zod` and `@mastra/core`. Ensure these are installed and compatible with your project.","severity":"gotcha","affected_versions":"*"},{"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.","message":"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.","severity":"breaking","affected_versions":">=1.12.0"},{"fix":"Pass an `observabilityContext` to relevant Mastra operations to enable tracing for RAG and graph interactions.","message":"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.","severity":"gotcha","affected_versions":">=1.24.0 (@mastra/core)"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.9.0 (@mastra/core)"},{"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.","message":"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.","severity":"deprecated","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-18T00:00:00.000Z","next_check":"2026-07-17T00:00:00.000Z","problems":[{"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.","cause":"The `mastra` package's executable is not in your system's PATH, or the package was not installed globally/linked correctly.","error":"mastra: command not found"},{"fix":"Run `npm install @mastra/core@'>=1.1.0-0 <2.0.0-0'` in your project to install a compatible version.","cause":"The `@mastra/core` package, a required peer dependency for `mastra`, is either missing or its installed version does not meet the compatibility requirements.","error":"Error: Peer dependency \"@mastra/core\" is not installed or incompatible. Expected \">=1.1.0-0 <2.0.0-0\"."},{"fix":"Run `npm install zod@'^3.25.0 || ^4.0.0'` in your project.","cause":"The `zod` validation library, a peer dependency, is not installed or its version is outside the supported range.","error":"Error: Zod peer dependency not found. Please install zod@^3.25.0 || ^4.0.0."},{"fix":"Ensure you initialize and pass an `observabilityContext` to the relevant RAG ingestion or query operations where tracing is desired.","cause":"You are attempting to use RAG tracing features without providing the necessary `observabilityContext` for instrumentation.","error":"Error: RAG tracing requires an 'observabilityContext'. Please configure one."},{"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.","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.","error":"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."}],"ecosystem":"npm"}