Mastra

Mastra API CLI Reference

How to use the mastra api CLI to interact with Mastra servers. Prefer fast, focused commands and compact JSON projections. Treat the installed CLI and server schema as the source of truth when discovery is needed.

Use this reference when the user asks to inspect or call agents, workflows, tools, MCP servers, memory threads, traces, logs, metrics, scores, datasets, experiments, or to debug/test mastra api commands.

This reference does not cover the Mastra Platform control plane (projects, environments, deploys, tokens, workspace provisioning); for those, see platform.md.

Setup

The CLI can interact with any reachable Mastra server:

• Local dev server: http://localhost:4111 from npm run dev

• Mastra platform deployment: Use the deployment URL

• Remote/self-hosted server: Use the server URL

• Hosted Mastra Platform Observability: https://observability.mastra.ai (auto-targeted by trace, span, log, score, and metric commands)

For local servers, mastra api defaults to http://localhost:4111:

npx mastra api agent list

For Mastra platform or remote servers, pass --url. For the sake of brevity in examples, $MASTRA_URL is used as a placeholder for the actual server URL which you need to set yourself:

npx mastra api --url $MASTRA_URL agent list

For Factory operations, activate the mastra-factory skill first. Use the user's actual Factory instance URL (not the platform API/dashboard URL). Explicit --url works from an empty directory. Recognized hosted Factory domains use saved mastra auth login credentials; check mastra auth whoami and offer login if needed. Custom/self-hosted deployments may use different authentication. Factory discovery uses bundled leaf contracts and root-level /web/* routes, not the runtime schema probe below.

For an unauthenticated local runtime server, verify the server once with a cheap check before resource calls:

MASTRA_URL="${MASTRA_URL:-http://localhost:4111}"
curl -fsS "$MASTRA_URL/api/system/api-schema" >/dev/null

If $MASTRA_URL is not reachable, ask for the correct deployment URL and set --url accordingly. For authenticated targets, use a supported read-only CLI call instead of treating an unauthenticated schema-probe failure as unreachability. Let the CLI use saved login on recognized platform hosts; for custom servers, have the user configure the deployment's approved authentication mechanism outside chat. Never request secret values in chat or inspect saved credential files.

For authenticated servers, pass repeatable headers:

npx mastra api --url "$MASTRA_URL" --header "Authorization: Bearer $TOKEN" agent list

Target resolution

Runtime commands (agent, workflow, tool, mcp, thread, memory, dataset, experiment) resolve the target in this order:

1. --url <url> for an explicit remote or self-hosted server.

2. http://localhost:4111 for a local mastra dev server.

3. .mastra-project.json for a Mastra platform project.

Observability commands (trace, span, log, score, metric) target https://observability.mastra.ai by default instead of a project deployment URL. EU projects use https://observability.eu.mastra.ai: the CLI picks it automatically from [email protected]. On older versions, EU requests time out with REQUEST_TIMEOUT; pass --url https://observability.eu.mastra.ai. The CLI resolves credentials in this order:

1. Explicit Authorization and X-Mastra-Project-Id headers passed with --header.

2. MASTRA_PLATFORM_ACCESS_TOKEN and MASTRA_PROJECT_ID from the environment.

3. Project metadata from .mastra-project.json for the project ID.

4. The Mastra CLI login token as an auth fallback.

For observability calls, no --url or --header is required if MASTRA_PLATFORM_ACCESS_TOKEN and MASTRA_PROJECT_ID are set, or if .mastra-project.json is present:

npx mastra api trace list '{"page":0,"perPage":10}'
npx mastra api metric names

Pass --url and --header only when overriding the hosted observability target or credentials.

Decision flow

1. Clear read-only request (list X, latest X, get X, summarize recent X): infer the resource and use the fast path first.

2. Mutating request (create, update, delete, run, resume, execute), unclear resource/action, failed fast path, or exact syntax requested: use narrow CLI discovery.

3. JSON input uncertain: use command-specific --schema.

4. Route behavior confusing: inspect /api/system/api-schema.

Start with these command groups when present; verify with mastra api --help if the group fails.

agent workflow tool mcp thread memory trace span log metric score dataset experiment

Fast path for read-only requests

Use conventional list/get commands first. Keep pages small and pipe through jq immediately.

Latest item:

npx mastra api <resource> list '{"page":0,"perPage":1}' \
  | jq '.data[0]'

Recent items:

npx mastra api <resource> list '{"page":0,"perPage":10}' \
  | jq '.data[]'

When the shape is known, project only the fields needed for the task:

npx mastra api <resource> list '{"page":0,"perPage":10}' \
  | jq '.data[] | {id, name, createdAt, status}'

Get details:

npx mastra api <resource> get <id> \
  | jq '.data'

When the shape is known, project only the fields needed for the task:

npx mastra api <resource> get <id> \
  | jq '.data | {id, name, createdAt, status}'

If a resource does not support the conventional shape, fall back to narrow --help for that resource/action.

Output control

• Do not use unfiltered --pretty during exploration.

• Always project list/get output with jq before reading details.

• Use perPage:1 for latest and perPage:10 or less for recent lists.

• If output is truncated or noisy, rerun with a narrower jq projection. Do not increase terminal output just to see more raw JSON.

• Fetch full JSON only when the user asks for raw output or compact projections are insufficient.

Fallback discovery

Use the narrowest discovery command that can answer the question. Example for traces:

npx mastra api trace --help
npx mastra api trace list --help
npx mastra api trace list --schema
npx mastra api trace query --help
npx mastra api trace query --schema
npx mastra api trace aggregate --help
npx mastra api trace aggregate --schema
npx mastra api span query --help
npx mastra api span query --schema
npx mastra api span aggregate --help
npx mastra api span aggregate --schema

Use trace query instead of trace list when selection requires recursive predicates, metadata filters, or conditions over related spans. First use trace query --help to confirm that the installed CLI exposes the command. The inline JSON query is required, and its cursor-bearing response stays nested under data. Read trace-query.md for availability checks, the division between CLI schema discovery and canonical documentation, query construction, and pagination.

Use trace aggregate when the answer is a count or measure (error rate, latency percentiles, tokens, cost) grouped by up to two dimensions or time buckets rather than a list of traces. It takes the same timeRange and where as trace query. See trace-query.md.

Use span query to list individual spans (including nested agent runs and tool calls) with flat span-field predicates, and span aggregate to compute the same measures grouped by span fields. See trace-query.md and trace-query.md.

Use top-level help only when the resource is unknown:

npx mastra api --help

Read --schema output as the contract:

• command: usage string

• examples: known-good examples

• positionals: required path/identity arguments

• input.required: whether JSON input is required

• input.schema: accepted CLI JSON input, including query/body fields

• schemas: raw server route schemas for deeper debugging

JSON and output contract

mastra api accepts at most one inline JSON object as input. Do not use stdin or files unless the user explicitly asks.

For non-GET routes, the CLI splits the one JSON object into query parameters and request body according to the server route schema.

Output envelopes:

{ "data": {} }
{ "data": [], "page": { "total": 0, "page": 0, "perPage": 0, "hasMore": false } }
{ "error": { "code": "...", "message": "...", "details": {} } }

Error handling

• INVALID_JSON: fix shell quoting; input must be one JSON object.

• MISSING_INPUT: run the same command with --schema and supply required JSON.

• MISSING_ARGUMENT: provide the positional shown by --help / --schema.

• HTTP_ERROR: inspect error.details, then compare against --schema or route schema.

• REQUEST_TIMEOUT: retry with larger --timeout, especially for workflow execution.

• SERVER_UNREACHABLE: verify the URL and the server check. If localhost is not running, ask whether the user wants to use a Mastra platform deployment or another remote server URL.

Route-level debugging

If CLI behavior seems wrong, inspect the route-derived schema manifest instead of guessing.

Find routes by path:

curl -fsS "$MASTRA_URL/api/system/api-schema" \
  | jq '.routes[] | select(.path | contains("/memory"))'

Inspect one route:

curl -fsS "$MASTRA_URL/api/system/api-schema" \
  | jq '.routes[] | select(.method == "POST" and .path == "/tools/:toolId/execute") | {pathParamSchema, queryParamSchema, bodySchema, responseShape}'

Known notes

• Tool and MCP tool execution accept raw tool input; explicit { "data": ... } also works.

• Workflow resume only works for suspended workflow runs.

• Working memory update requires the agent's memory to have working memory enabled.

• Empty lists may simply mean the server has no matching stored data yet.

• trace list and trace get return lightweight payloads by default (no span input, output, attributes, or metadata). Pass --verbose to fetch full span records, or use trace span <traceId> <spanId> to fetch one specific span in full.

• trace query requires inline JSON, queries completed traces, and defaults to keyset pagination: pass data.page.next unchanged as page.after with the same query shape. Numbered pages and delta polling use different response metadata; see trace-query.md.

• trace aggregate requires inline JSON and isn't paginated; when truncated is true, narrow the selection.

• span query requires inline JSON and pages like trace query: pass data.page.next unchanged as page.after. span aggregate isn't paginated, like trace aggregate.