Introducing Mastra CLI Actions for Claude Code, Cursor, and Codex

Claude Code, Cursor, and Codex can now test drive your Mastra projects with CLI Actions.

Coding agents have been able to write Mastra code for a while now — through Mastra skills and the MCP docs server. What they couldn't do was run projects.

CLI Actions expose the same functionality as Studio, but as commands your coding agent can use to:

Run agents and workflows: Call an agent or run a workflow with one command.
Search memory: Pull threads and messages to see what the agent's been doing.
Investigate failures: Query traces and logs to find what broke.
Improve agents: Turn failures into datasets, run experiments, check results.

For example, imagine your agent's response is wrong. You describe what's happening to your coding agent; it pulls the trace, spots the problem, edits the instructions, then runs an experiment to confirm the fix — all by itself.

Get started

Install the CLI:

Terminal

npm install mastra@latest -g

note

Requires mastra@1.9.0 or later, added in PR #16128.

Run agents and workflows

CLI Actions target a live Mastra server using the --url flag. List what's available, invoke agents, kick off workflows, execute tools, or inspect MCP servers and their exposed tools.

mastra api --url http://localhost:4111 agent list
mastra api --url http://localhost:4111 agent get weather-agent
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
mastra api --url http://localhost:4111 mcp tool list <serverId>

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

Workflow runs

Track, resume, or cancel any in-flight workflow run:

mastra api workflow run list weather-workflow
mastra api workflow run get weather-workflow <run-id>
mastra api workflow run resume weather-workflow <run-id> '{"stepId":"fetch-weather","resumeData":{"approved":true}}'
mastra api workflow run cancel weather-workflow <run-id>

Search memory

Dig into a conversation that went off the rails. List threads, fetch messages, search across resources, or inspect the agent's working memory:

mastra api thread list '{"resourceId":"user_123"}'
mastra api thread create '{"agentId":"weather-agent","resourceId":"user_123","title":"Support conversation"}'
mastra api thread messages <thread-id>
mastra api memory search '{"agentId":"weather-agent","resourceId":"user_123","searchQuery":"London weather","limit":10}'
mastra api memory current get <thread-id>
mastra api memory current update <thread-id> '{"workingMemory":{...}}'
mastra api memory status

Investigate failures

Add your MASTRA_PLATFORM_ACCESS_TOKEN and MASTRA_PROJECT_ID to your .env, then list traces and logs, zoom into a single trace or span, or run aggregate / breakdown / time-series queries over your metrics:

mastra api trace list
mastra api trace get <trace-id>
mastra api trace span <trace-id> <span-id>
mastra api log list
mastra api metric names
mastra api metric aggregate '{"name":["mastra_model_total_output_tokens"],"aggregation":"sum"}'
mastra api metric breakdown '{"name":"mastra_model_total_output_tokens","groupBy":"agentId"}'
mastra api metric timeseries '{"name":"mastra_model_total_output_tokens","interval":"1h"}'

See observability on Mastra platform for setup instructions.

Improve agents

Evals work just like they do in Studio. Build a dataset, run an experiment, check the results, and inspect individual scores:

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

Beyond the local loop

CLI Actions also handle the ops side: ship projects, manage environment variables, control your running instance, and 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: