Close the Loop With the Upgraded Mastra CLI

Your coding agent already writes Mastra code. Now it can help run your Mastra projects too.

The new Mastra CLI is your agent's direct line to the runtime. It can invoke agents and run workflows. Execute tools. Inspect memory, run evals, and query traces and logs. It even handles environment management and deploys.

This adds to our coding-agent tooling, joining Mastra skills and the MCP docs server.

Put it all together, and your coding agent can drive a full Mastra workflow end-to-end. Think: testing prompts against traces, pulling failure patterns into a new dataset, then checking logs after a change before pushing the fix.

Why we shipped this

Debugging agents is all about context. You need to see what's happening at runtime to ship something you can trust.

If you're a coding agent running a Mastra project, you need this from day one: a way to invoke agents, query traces, and ship updates.

That's why we built it into the CLI. It's not just a local feature in Studio anymore. It's a terminal surface, so your agent can save its work and share the results with the team.

Get started

Install the CLI:

npm install mastra@latest -g

Runtime

Runtime commands target a live Mastra server using the --url flag. Use them to invoke agents, kick off workflows, execute tools, or list and inspect your MCP servers.

mastra api --url http://localhost:4111 agent run weather-agent '{"messages":"What is the weather in London?"}'
mastra api --url http://localhost:4111 workflow run start weather-workflow '{"inputData":{"city":"London"}}'
mastra api --url http://localhost:4111 tool execute get-weather '{"location":"London"}'
mastra api --url http://localhost:4111 mcp list

For production, just point --url at your deployed URL—something like https://acme.com/api.

Memory

Need to dig into a conversation that went off the rails? The memory subcommands are your friend:

mastra api thread create '{"agentId":"weather-agent","resourceId":"user_123","title":"Support conversation"}'
mastra api memory search '{"agentId":"weather-agent","resourceId":"user_123","searchQuery":"London weather","limit":10}'
mastra api memory current get '{"threadId":"thread_abc123","agentId":"weather-agent"}'

Evals

Evals work just like they do in Studio. You need a dataset, an experiment, and then you check the results:

mastra api dataset create '{"name":"weather-eval"}'
mastra api experiment run <dataset-id> '{"name":"baseline"}'
mastra api experiment results <dataset-id> <experiment-id>

Observability

For observability, add your MASTRA_PLATFORM_ACCESS_TOKEN and MASTRA_PROJECT_ID to your .env. From there, you can query traces, logs, scores, and metrics for all your platform projects:

mastra api trace list
mastra api log list
mastra api score list
mastra api metric aggregate '{"name":["mastra_model_total_output_tokens"],"aggregation":"sum"}'

See observability on Mastra platform for setup instructions.

Platform and project

Platform commands are for the ops side of things. Ship projects, manage environment variables, control your running instance, and even diagnose failed deploys.

mastra studio deploy --yes
mastra server env pull > .env.production
mastra server restart
mastra studio deploy suggestions <deploy-id>

On the project level, mastra lint --preflight runs a pre-ship validation, mastra migrate -y handles DB migrations, and mastra auth login takes care of authentication.

For more information and full setup instructions, see:

• CLI commands reference
• mastra api reference
• Build with AI