Skip to main content

create-mastra

Create a standalone Mastra project. By default, create-mastra installs a default starter and configures it for your selected model provider.

npx create-mastra@latest

Creation modes
Direct link to Creation modes

Default starter
Direct link to Default starter

The default starter creates an agent harness with workspace tools, memory, task tracking, web access, recurring schedules, storage, and observability. Select OpenAI, Anthropic, Gemini, or xAI as your model provider.

Provide both the project name and provider to create the project without prompts. This example uses Anthropic; you can also pass openai, google, or xai:

npx create-mastra@latest my-mastra-project --llm anthropic

Omit --llm to select the provider and optionally enter its API key interactively. The interactive setup also offers to connect your project to the Mastra platform. If enabled, the command opens the browser authentication flow and creates a platform project with the same name as the local project. It then writes MASTRA_PLATFORM_ACCESS_TOKEN and MASTRA_PROJECT_ID to .env.

Template
Direct link to Template

Use a template slug or a public GitHub URL:

npx create-mastra@latest my-mastra-project --template agent-harness
npx create-mastra@latest my-mastra-project --template https://github.com/mastra-ai/template-agent-harness

Leave the template value blank to select a template interactively:

npx create-mastra@latest my-mastra-project --template

Template authors own their dependencies, models, environment variables, and source code. create-mastra doesn't apply --llm or --llm-api-key.

Empty scaffold
Direct link to Empty scaffold

Use --empty to create a provider-free project without agents, examples, model SDKs, or environment files:

npx create-mastra@latest my-empty-project --empty

Automatic setup
Direct link to Automatic setup

After installing dependencies, the command:

  1. Detects supported coding assistants on PATH and installs Mastra skills. If none are detected, it installs universal skills.
  2. Creates an initial Git commit when the current directory and generated project aren't already inside Git repositories.

Use --no-skills or --no-git to skip these steps. Skills and Git setup failures produce warnings but don't remove a successfully created project.

Conflicts and validation
Direct link to Conflicts and validation

  • --empty and --template can't be used together.
  • --llm and --llm-api-key are only valid for the default starter project.
  • The project name must be a safe, lowercase, single directory name and the target must not already exist.

Invalid input is rejected before templates are fetched or files are created.

Arguments and flags
Direct link to Arguments and flags

[project-name]?:

string
Project directory and package name. When omitted, the command prompts for it.

--empty?:

boolean
Create a minimal, provider-free Mastra project.

-l, --llm <provider>?:

string
Managed agent-harness provider: openai, anthropic, google, or xai.

-k, --llm-api-key <key>?:

string
Write the selected provider API key to the generated .env file.

--no-skills?:

boolean
Skip automatic Mastra skills installation.

--no-git?:

boolean
Skip automatic Git initialization and the initial commit.

-t, --template [template]?:

string
Use a template slug or public GitHub URL. Omit the value to select interactively.

--timeout <milliseconds>?:

number
Positive integer timeout for dependency installation. Defaults to 60000.

--version?:

boolean
Print the create-mastra version.

--help?:

boolean
Display command help.

Telemetry
Direct link to Telemetry

Mastra collects anonymous CLI usage information, such as the operating system, Mastra version, and Node.js version. You can review the analytics source.

Set MASTRA_TELEMETRY_DISABLED=1 to opt out:

MASTRA_TELEMETRY_DISABLED=1 npx create-mastra@latest my-project --empty
On this page