create-factory

Create a Mastra Factory project with an interactive wizard. By default, create-factory installs dependencies and connects the project to the Mastra platform resources.

npm

npx create-factory@latest

pnpm

pnpm dlx create-factory@latest

Yarn

yarn dlx create-factory@latest

Bun

bun x create-factory@latest

Creation modes

Default template

The command downloads the Software Factory template. Provide a project name or enter one when prompted:

npm

npx create-factory@latest my-mastra-factory

pnpm

pnpm dlx create-factory@latest my-mastra-factory

Yarn

yarn dlx create-factory@latest my-mastra-factory

Bun

bun x create-factory@latest my-mastra-factory

Platform setup uses your existing Mastra credentials or opens a browser sign-in flow. It resolves the organization and prompts for a project region. Use --org and --region to supply those choices:

npm

npx create-factory@latest my-mastra-factory --org my-org --region eu

pnpm

pnpm dlx create-factory@latest my-mastra-factory --org my-org --region eu

Yarn

yarn dlx create-factory@latest my-mastra-factory --org my-org --region eu

Bun

bun x create-factory@latest my-mastra-factory --org my-org --region eu

These flags don't bypass authentication.

Without platform setup

Use --no-platform to skip sign-in and resource provisioning:

npm

npx create-factory@latest my-mastra-factory --no-platform

pnpm

pnpm dlx create-factory@latest my-mastra-factory --no-platform

Yarn

yarn dlx create-factory@latest my-mastra-factory --no-platform

Bun

bun x create-factory@latest my-mastra-factory --no-platform

The command still downloads the template and installs dependencies. It copies .env.example to .env without filling in platform credentials. Configure .env before starting the project.

Automatic setup

The command performs these steps in order:

1. Downloads the template into a new directory and updates the package name.
2. Copies .env.example to .env and attempts to restrict its permissions to the current user.
3. Installs dependencies using the detected package manager, falling back to npm.
4. Provisions platform resources unless --no-platform is set.
5. Ensures .env is ignored by Git, then initializes a repository and creates an initial commit.

For the default template, start the development server from the generated directory:

npm

cd my-mastra-factory
npm run dev

pnpm

cd my-mastra-factory
pnpm run dev

Yarn

cd my-mastra-factory
yarn dev

Bun

cd my-mastra-factory
bun run dev

The Factory UI is available at http://localhost:4111.

Platform provisioning

Platform setup creates a project with Factory enabled and an organization API key. It also ensures a production environment exists and attaches a Neon Postgres database. The selected project region determines the database region:

Project region	Neon region
eu	aws-eu-central-1
us	aws-us-west-2

Successful provisioning writes these values to .env, preserving unrelated entries:

Variable	Value
MASTRA_ORGANIZATION_ID	Selected organization ID
MASTRA_PROJECT_ID	Created platform project ID
MASTRA_PLATFORM_SECRET_KEY	Newly minted organization API key
MASTRA_ENVIRONMENT_ID	Production environment ID
DATABASE_URL	Neon database connection string

If provisioning fails, the command warns and preserves the local project. Values obtained before the failure are still written to .env, so you can complete the remaining configuration manually. Skipping browser sign-in also allows local setup to continue without provisioning.

Arguments and flags

[project-name]?:

string

Project directory and package name. Prompts when omitted. The target directory must not already exist.

--template <template-name>?:

string

Public GitHub template URL. Defaults to https://github.com/mastra-ai/softwarefactory-template.

--no-platform?:

boolean

Skip Mastra platform sign-in, project creation, API key creation, and Neon provisioning. Platform setup runs by default.

--org <org>?:

string

Organization ID or name. Skips the organization picker. Ignored when --no-platform is set.

--region <region>?:

'eu' | 'us'

Platform project region. Prompts during platform setup when omitted. Other values are rejected before downloading the template, including with --no-platform.

-v, --version?:

boolean

Print the create-factory version.

-h, --help?:

boolean

Display command help.

Environment variables

These variables configure the CLI process, rather than the generated Factory server:

MASTRA_API_TOKEN?:

string

Authenticate platform API requests instead of using saved credentials or browser sign-in.

MASTRA_ORG_ID?:

string

Select the organization without prompting. An explicit --org flag takes precedence.

MASTRA_TELEMETRY_DISABLED?:

string

Set to 1, true, or yes to disable CLI telemetry. Values are case-insensitive.

Telemetry

The CLI collects usage information, including the package manager and whether platform provisioning succeeds. Command telemetry records whether you use the default template or supply an organization, rather than the custom template URL or organization value. Sensitive argument values are redacted from failure telemetry.

To opt out:

npm

MASTRA_TELEMETRY_DISABLED=1 npx create-factory@latest my-mastra-factory --no-platform

pnpm

MASTRA_TELEMETRY_DISABLED=1 pnpm dlx create-factory@latest my-mastra-factory --no-platform

Yarn

MASTRA_TELEMETRY_DISABLED=1 yarn dlx create-factory@latest my-mastra-factory --no-platform

Bun

MASTRA_TELEMETRY_DISABLED=1 bun x create-factory@latest my-mastra-factory --no-platform