1# Create Mastra Reference
2 
3Complete guide for creating new Mastra projects. Includes both quickstart CLI method and detailed manual installation.
4 
5**Official documentation: [mastra.ai/docs](https://mastra.ai/docs)**
6 
7## Get started
8 
9Ask: **"How would you like to create your Mastra project?"**
10 
111. **Quick Setup**: Copy and run: `npm create mastra@latest`
122. **Guided Setup**: I walk you through each step, you approve commands
133. **Automatic Setup**: I create everything, just give me your API key
14 
15> **For AI agents:** The CLI is interactive. Use **Automatic Setup** to create files using the steps in "Automatic Setup / Manual Installation" below.
16 
17## Prerequisites
18 
19- An API key from a supported model provider (OpenAI, Anthropic, Google, etc.)
20 
21## Quick Setup (user runs CLI)
22 
23Create a new Mastra project with one command:
24 
25```bash
26npm create mastra@latest
27```
28 
29**Other package managers:**
30 
31```bash
32pnpm create mastra@latest
33yarn create mastra@latest
34bun create mastra@latest
35```
36 
37## CLI flags
38 
39**Skip the example agent:**
40 
41```bash
42npm create mastra@latest --no-example
43```
44 
45**Use a specific template:**
46 
47```bash
48npm create mastra@latest --template <template-name>
49```
50 
51## Automatic setup / manual installation
52 
53**Use this for automatic setup** (AI creates all files) or when you prefer manual control.
54 
55Follow these steps to create a complete Mastra project:
56 
57### Step 1: Create project directory
58 
59```bash
60mkdir my-first-agent && cd my-first-agent
61npm init -y
62```
63 
64### Step 2: Install dependencies
65 
66```bash
67npm install -D typescript @types/node mastra@latest
68npm install @mastra/core@latest zod@^4
69```
70 
71### Step 3: Configure package scripts
72 
73Add to `package.json`:
74 
75```json
76{
77  "scripts": {
78    "dev": "mastra dev",
79    "build": "mastra build"
80  }
81}
82```
83 
84### Step 4: Configure TypeScript
85 
86Create `tsconfig.json`:
87 
88```json
89{
90  "compilerOptions": {
91    "target": "ES2022",
92    "module": "ES2022",
93    "moduleResolution": "bundler",
94    "esModuleInterop": true,
95    "forceConsistentCasingInFileNames": true,
96    "strict": true,
97    "skipLibCheck": true,
98    "noEmit": true,
99    "outDir": "dist"
100  },
101  "include": ["src/**/*"]
102}
103```
104 
105**Important:** Mastra requires `"module": "ES2022"` and `"moduleResolution": "bundler"`. CommonJS will cause errors.
106 
107### Step 5: Create environment file
108 
109Create `.env` with your API key:
110 
111```env
112GOOGLE_GENERATIVE_AI_API_KEY=<your-api-key>
113```
114 
115Or use `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, etc.
116 
117### Step 6: Create weather tool
118 
119Create `src/mastra/tools/weather-tool.ts`:
120 
121```typescript
122import { createTool } from "@mastra/core/tools";
123import { z } from "zod";
124 
125export const weatherTool = createTool({
126  id: "get-weather",
127  description: "Get current weather for a location",
128  inputSchema: z.object({
129    location: z.string().describe("City name"),
130  }),
131  outputSchema: z.object({
132    output: z.string(),
133  }),
134  execute: async () => {
135    return { output: "The weather is sunny" };
136  },
137});
138```
139 
140### Step 7: Create weather agent
141 
142Create `src/mastra/agents/weather-agent.ts`:
143 
144```typescript
145import { Agent } from "@mastra/core/agent";
146import { weatherTool } from "../tools/weather-tool";
147 
148export const weatherAgent = new Agent({
149  id: "weather-agent",
150  name: "Weather Agent",
151  instructions: `
152      You are a helpful weather assistant that provides accurate weather information.
153 
154      Your primary function is to help users get weather details for specific locations. When responding:
155      - Always ask for a location if none is provided
156      - If the location name isn't in English, please translate it
157      - If giving a location with multiple parts (e.g. "New York, NY"), use the most relevant part (e.g. "New York")
158      - Include relevant details like humidity, wind conditions, and precipitation
159      - Keep responses concise but informative
160 
161      Use the weatherTool to fetch current weather data.
162`,
163  model: "google/gemini-2.5-pro",
164  tools: { weatherTool },
165});
166```
167 
168**Note:** Model format is `"provider/model-name"`. Examples:
169 
170- `"google/gemini-2.5-pro"`
171- `"openai/gpt-5.4"`
172- `"anthropic/claude-sonnet-4-5"`
173 
174### Step 8: Create mastra entry point
175 
176Create `src/mastra/index.ts`:
177 
178```typescript
179import { Mastra } from "@mastra/core";
180import { weatherAgent } from "./agents/weather-agent";
181 
182export const mastra = new Mastra({
183  agents: { weatherAgent },
184});
185```
186 
187### Step 9: Launch Mastra Studio
188 
189Launch the development server:
190 
191```bash
192npm run dev
193```
194 
195Access Studio at `http://localhost:4111` to test your agent.
196 
197## Next steps
198 
199After creating your project with `create mastra`:
200 
201- **Customize the example agent** in `src/mastra/agents/weather-agent.ts`
202- **Add new agents** - see [Agents documentation](https://mastra.ai/docs/agents/overview)
203- **Create workflows** - see [Workflows documentation](https://mastra.ai/docs/workflows/overview)
204- **Add more tools** to extend agent capabilities
205- **Integrate into your app** - see framework guides at [mastra.ai/docs](https://mastra.ai/docs)
206 
207## Troubleshooting
208 
209| Issue              | Solution                                                                             |
210| ------------------ | ------------------------------------------------------------------------------------ |
211| API key not found  | Make sure your `.env` file has the correct key                                       |
212| Studio won't start | Check that port 4111 is available                                                    |
213| CommonJS errors    | Ensure `tsconfig.json` uses `"module": "ES2022"` and `"moduleResolution": "bundler"` |
214| Command not found  | Ensure you're using Node.js 20+                                                      |
215 
216## Resources
217 
218- [Docs](https://mastra.ai/docs)
219- [Installation](https://mastra.ai/docs/getting-started/installation)
220- [Agents](https://mastra.ai/docs/agents/overview)
221- [Workflows](https://mastra.ai/docs/workflows/overview)
222- [GitHub](https://github.com/mastra-ai/mastra)
223