Mastra CLI

# Install globally
npm install -g mastra

# Create new project
mastra create my-app

# Start development
cd my-app
mastra dev

type Component = 'agents' | 'workflows' | 'tools' | 'scorers';
type LLMProvider = 'openai' | 'anthropic' | 'groq' | 'google' | 'cerebras' | 'mistral';

// Safe imports - don't trigger CLI
import { PosthogAnalytics, getAnalytics, setAnalytics } from "mastra/analytics";
import { create } from "mastra/dist/commands/create/create";

// Create project programmatically
await create({
  projectName: "my-app",
  components: ["agents", "workflows"],
  llmProvider: "openai",
  addExample: true
});

# Disable telemetry
MASTRA_TELEMETRY_DISABLED=1

# Server configuration
PORT=4111                    # Default server port
HOST=localhost               # Default server host

# Database
DATABASE_URL=postgresql://user:pass@host:port/db

# Debug logging
DEBUG=1                      # Enable CLI debug logs
MASTRA_DEBUG=1              # Enable Mastra debug logs

# Interactive (recommended)
mastra create

# With options
mastra create my-app --default
mastra create my-app --components agents,workflows --llm openai

cd my-app
npm install
mastra dev              # Start dev server
mastra studio           # Open Studio UI (different terminal)
mastra lint             # Check configuration

mastra build --studio   # Build with UI
mastra start            # Run production server

mastra scorers list     # See available scorers
mastra scorers add answer-relevancy

0   // Success
1   // Error (validation failure, runtime error)
130 // Interrupted (Ctrl+C)

my-app/
  ├── package.json              # With mastra dependency
  ├── .env                      # LLM API keys (if provided)
  ├── .gitignore               # Standard Node.js ignores
  └── src/                      # Source directory (configurable)
      └── mastra/               # Mastra configuration
          ├── index.ts          # Main entry point
          ├── agents/           # AI agents (if selected)
          ├── workflows/        # Workflows (if selected)
          ├── tools/            # Tools (if selected)
          └── scorers/          # Scorers (if selected)

.mastra/
  └── output/                   # Production build
      ├── index.js              # Bundled server
      ├── package.json          # Runtime dependencies
      └── studio/               # Studio UI (if --studio flag)

// Valid
"my-app"
"my_app"
"@scope/my-app"

// Invalid
"my app"         // No spaces
".hidden"        // Can't start with .
"node_modules"   // Reserved name

// Valid
"agents,workflows,tools"
"scorers"

// Invalid
"agent"          // Must be plural
"workflow"       // Must be plural

export MASTRA_TELEMETRY_DISABLED=1
export CI=1
npm install
mastra lint
mastra migrate --yes
mastra build --studio

FROM node:22.13.0-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
ENV MASTRA_TELEMETRY_DISABLED=1
RUN npx mastra build --studio
ENV PORT=4111
ENV HOST=0.0.0.0
CMD ["npx", "mastra", "start"]

// Detection priority
package-lock.json → npm
pnpm-lock.yaml → pnpm
yarn.lock → yarn
bun.lockb → bun

// Search order
src/mastra/ → src/ → lib/mastra/ → mastra/ → .