Quick Start Guide

Get up and running with Mastra CLI in minutes.

Prerequisites

• Node.js: >=22.13.0
• Package Manager: npm, pnpm, yarn, or bun
• LLM API Key: OpenAI, Anthropic, Groq, Google, Cerebras, or Mistral

Installation

Option 1: Global Installation

npm install -g mastra
mastra --version

Option 2: Use with npx (No Installation)

npx mastra create my-app

Create Your First Project

Interactive Mode (Recommended)

mastra create my-app

You'll be prompted for:

1. Package Manager: npm, pnpm, yarn, or bun
2. Components: agents, workflows, tools, scorers
3. LLM Provider: openai, anthropic, groq, google, cerebras, mistral
4. API Key: Your LLM provider API key
5. Include Examples: Yes/No

Quick Start with Defaults

mastra create my-app --default

This creates a project with:

• Directory: src/
• Components: agents, workflows, tools
• LLM: OpenAI
• Examples: Included

Custom Configuration

mastra create my-app \
  --components agents,workflows \
  --llm openai \
  --llm-api-key sk-... \
  --example \
  --dir src/

Project Structure

After creation, you'll have:

my-app/
├── package.json              # Mastra dependency included
├── .env                      # API keys (git-ignored)
├── .gitignore               # Standard Node.js ignores
├── node_modules/            # Dependencies
└── src/
    └── mastra/
        ├── index.ts          # Main Mastra configuration
        ├── agents/           # AI agents
        │   └── example-agent.ts
        ├── workflows/        # Workflows
        │   └── example-workflow.ts
        └── tools/            # Tools
            └── example-tool.ts

Start Development Server

cd my-app
npm install  # If not already installed
mastra dev

The development server starts on http://localhost:4111 by default.

Development Server Features

• Hot Reload: Automatic restart on file changes
• TypeScript Support: Native TypeScript compilation
• Debug Mode: Run with --debug flag for detailed logs
• HTTPS: Use --https flag for local HTTPS

Custom Port/Host

PORT=8080 mastra dev
HOST=0.0.0.0 mastra dev  # Allow external connections

Open Mastra Studio

In a separate terminal:

cd my-app
mastra studio

Studio opens on http://localhost:3000 and provides:

• Agent testing interface
• Workflow visualization
• Tool debugging
• Log monitoring

Verify Your Setup

Run Linter

mastra lint

This checks:

• Valid Mastra configuration
• All files referenced exist
• TypeScript syntax
• Missing dependencies

Test Your First Agent

1. Open src/mastra/agents/example-agent.ts
2. Modify the agent configuration
3. Save the file (dev server auto-reloads)
4. Test in Studio UI

Add Components

Add a Scorer

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

Initialize in Existing Project

If you have an existing Node.js project:

cd existing-project
mastra init

Follow the same prompts as create.

Environment Variables

Create or update .env:

# LLM API Keys
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GROQ_API_KEY=gsk_...

# Optional: Database
DATABASE_URL=postgresql://user:pass@localhost:5432/mastra

# Optional: Disable telemetry
MASTRA_TELEMETRY_DISABLED=1

Build for Production

mastra build

Build output in .mastra/output/:

• index.js: Bundled server (~1-2MB)
• package.json: Runtime dependencies
• Source maps included

Build with Studio UI

mastra build --studio

Adds Studio UI to build (~6-12MB total).

Run Production Server

mastra start

Or with custom environment:

mastra start --env .env.production

Common Issues

Port Already in Use

# Solution 1: Use different port
PORT=8080 mastra dev

# Solution 2: Kill process
lsof -ti:4111 | xargs kill -9

Node.js Version Too Old

# Check version
node --version

# Upgrade with nvm
nvm install 22
nvm use 22

Missing API Key

# Add to .env file
echo "OPENAI_API_KEY=sk-..." >> .env

Package Installation Timeout

# Increase timeout (milliseconds)
mastra create my-app --timeout 120000

Next Steps

1. Explore Examples: Check the example code in your project
2. Read Guides:
   • Development Workflow
   • Production Deployment
3. Check Reference: CLI Commands
4. Try Examples: Real-World Scenarios

Quick Reference

# Create
mastra create my-app
mastra create my-app --default
mastra init

# Develop
mastra dev
mastra dev --https
mastra dev --debug
mastra studio

# Validate
mastra lint

# Build
mastra build
mastra build --studio

# Run
mastra start

# Scorers
mastra scorers list
mastra scorers add <name>

# Help
mastra --help
mastra <command> --help

Telemetry

Mastra collects optional usage analytics via PostHog.

Disable:

export MASTRA_TELEMETRY_DISABLED=1

Or add to .env:

MASTRA_TELEMETRY_DISABLED=1

Getting Help

• Run mastra --help for command overview
• Run mastra <command> --help for command-specific help
• Check error handling guide for common issues
• Review examples for usage patterns