DocsReferenceCLIDev

mastra dev Reference

The mastra dev command starts a development server that exposes REST endpoints for your agents, tools, and workflows,

Parameters

--dir?:

string
Specifies the path to your Mastra folder (containing agents, tools, and workflows). Defaults to the current working directory.

--env?:

string
Specifies which environment file to load. Defaults to `.env.development`, falling back to `.env` if not found.

--tools?:

string
Comma-separated paths to additional tool directories that should be registered. For example: 'src/tools/dbTools,src/tools/scraperTools'.

--port?:

number
Specifies the port number for the development server. Defaults to 4111.

Routes

Starting the server with mastra dev exposes a set of REST endpoints by default:

Agent Routes

Agents are expected to be exported from src/mastra/agents.

• GET /api/agents

  • Lists the registered agents found in your Mastra folder. • POST /api/agents/:agentId/generate
  • Sends a text-based prompt to the specified agent, returning the agent’s response.

Tool Routes

Tools are expected to be exported from src/mastra/tools (or the configured tools directory).

• POST /api/tools/:toolName

  • Invokes a specific tool by name, passing input data in the request body.

Workflow Routes

Workflows are expected to be exported from src/mastra/workflows (or the configured workflows directory).

• POST /api/workflows/:workflowName/start

  • Starts the specified workflow. • POST /api/workflows/:workflowName/:instanceId/event
  • Sends an event or trigger signal to an existing workflow instance. • GET /api/workflows/:workflowName/:instanceId/status
  • Returns status info for a running workflow instance.

OpenAPI Specification

• GET /openapi.json

  • Returns an auto-generated OpenAPI specification for your project’s endpoints.

Additional Notes

The port defaults to 4111.

Make sure you have your environment variables set up in your .env.development or .env file for any providers you use (e.g., OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.).

Example request

To test an agent after running mastra dev:

curl -X POST http://localhost:4111/api/agents/myAgent/generate \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "user", "content": "Hello, how can you assist me today?" }
    ]
  }'

Related Docs

EngineDeploy
MIT 2025 © Nextra.