1# Mastra API CLI Reference
2 
3How 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.
4 
5Use 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.
6 
7## Setup
8 
9The CLI can interact with any reachable Mastra server:
10 
11- Local dev server: `http://localhost:4111` from `npm run dev`
12- Mastra platform deployment: Use the deployment URL
13- Remote/self-hosted server: Use the server URL
14- Hosted Mastra Platform Observability: `https://observability.mastra.ai` (auto-targeted by `trace`, `log`, `score`, and `metric` commands)
15 
16For local servers, `mastra api` defaults to `http://localhost:4111`:
17 
18```bash
19npx mastra api agent list
20```
21 
22For 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:
23 
24```bash
25npx mastra api --url $MASTRA_URL agent list
26```
27 
28Verify the server once with a cheap check before resource calls:
29 
30```bash
31MASTRA_URL="${MASTRA_URL:-http://localhost:4111}"
32curl -fsS "$MASTRA_URL/api/system/api-schema" >/dev/null
33```
34 
35If `$MASTRA_URL` is not reachable, the user may be using a Mastra platform deployment or remote URL. Ask for the correct server URL and set `--url` accordingly. If authentication is required, ask the user for the necessary token or credentials and set them in the environment for subsequent commands.
36 
37For authenticated servers, pass repeatable headers:
38 
39```bash
40npx mastra api --url "$MASTRA_URL" --header "Authorization: Bearer $TOKEN" agent list
41```
42 
43### Target resolution
44 
45Runtime commands (`agent`, `workflow`, `tool`, `mcp`, `thread`, `memory`, `dataset`, `experiment`) resolve the target in this order:
46 
471. `--url <url>` for an explicit remote or self-hosted server.
482. `http://localhost:4111` for a local `mastra dev` server.
493. `.mastra-project.json` for a Mastra platform project.
50 
51Observability commands (`trace`, `log`, `score`, `metric`) target `https://observability.mastra.ai` by default instead of a project deployment URL. The CLI resolves credentials in this order:
52 
531. Explicit `Authorization` and `X-Mastra-Project-Id` headers passed with `--header`.
542. `MASTRA_PLATFORM_ACCESS_TOKEN` and `MASTRA_PROJECT_ID` from the environment.
553. Project metadata from `.mastra-project.json` for the project ID.
564. The Mastra CLI login token as an auth fallback.
57 
58For 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:
59 
60```bash
61npx mastra api trace list '{"page":0,"perPage":10}'
62npx mastra api metric names
63```
64 
65Pass `--url` and `--header` only when overriding the hosted observability target or credentials.
66 
67## Decision flow
68 
691. Clear read-only request (`list X`, `latest X`, `get X`, `summarize recent X`): infer the resource and use the fast path first.
702. Mutating request (`create`, `update`, `delete`, `run`, `resume`, `execute`), unclear resource/action, failed fast path, or exact syntax requested: use narrow CLI discovery.
713. JSON input uncertain: use command-specific `--schema`.
724. Route behavior confusing: inspect `/api/system/api-schema`.
73 
74Start with these command groups when present; verify with `mastra api --help` if the group fails.
75 
76```text
77agent workflow tool mcp thread memory trace log metric score dataset experiment
78```
79 
80## Fast path for read-only requests
81 
82Use conventional `list`/`get` commands first. Keep pages small and pipe through `jq` immediately.
83 
84Latest item:
85 
86```bash
87npx mastra api <resource> list '{"page":0,"perPage":1}' \
88  | jq '.data[0]'
89```
90 
91Recent items:
92 
93```bash
94npx mastra api <resource> list '{"page":0,"perPage":10}' \
95  | jq '.data[]'
96```
97 
98When the shape is known, project only the fields needed for the task:
99 
100```bash
101npx mastra api <resource> list '{"page":0,"perPage":10}' \
102  | jq '.data[] | {id, name, createdAt, status}'
103```
104 
105Get details:
106 
107```bash
108npx mastra api <resource> get <id> \
109  | jq '.data'
110```
111 
112When the shape is known, project only the fields needed for the task:
113 
114```bash
115npx mastra api <resource> get <id> \
116  | jq '.data | {id, name, createdAt, status}'
117```
118 
119If a resource does not support the conventional shape, fall back to narrow `--help` for that resource/action.
120 
121## Output control
122 
123- Do not use unfiltered `--pretty` during exploration.
124- Always project list/get output with `jq` before reading details.
125- Use `perPage:1` for latest and `perPage:10` or less for recent lists.
126- If output is truncated or noisy, rerun with a narrower `jq` projection. Do not increase terminal output just to see more raw JSON.
127- Fetch full JSON only when the user asks for raw output or compact projections are insufficient.
128 
129## Fallback discovery
130 
131Use the narrowest discovery command that can answer the question. Example for traces:
132 
133```bash
134npx mastra api trace --help
135npx mastra api trace list --help
136npx mastra api trace list --schema
137```
138 
139Use top-level help only when the resource is unknown:
140 
141```bash
142npx mastra api --help
143```
144 
145Read `--schema` output as the contract:
146 
147- `command`: usage string
148- `examples`: known-good examples
149- `positionals`: required path/identity arguments
150- `input.required`: whether JSON input is required
151- `input.schema`: accepted CLI JSON input, including query/body fields
152- `schemas`: raw server route schemas for deeper debugging
153 
154## JSON and output contract
155 
156`mastra api` accepts at most one inline JSON object as input. Do not use stdin or files unless the user explicitly asks.
157 
158For non-GET routes, the CLI splits the one JSON object into query parameters and request body according to the server route schema.
159 
160Output envelopes:
161 
162```json
163{ "data": {} }
164{ "data": [], "page": { "total": 0, "page": 0, "perPage": 0, "hasMore": false } }
165{ "error": { "code": "...", "message": "...", "details": {} } }
166```
167 
168## Error handling
169 
170- `INVALID_JSON`: fix shell quoting; input must be one JSON object.
171- `MISSING_INPUT`: run the same command with `--schema` and supply required JSON.
172- `MISSING_ARGUMENT`: provide the positional shown by `--help` / `--schema`.
173- `HTTP_ERROR`: inspect `error.details`, then compare against `--schema` or route schema.
174- `REQUEST_TIMEOUT`: retry with larger `--timeout`, especially for workflow execution.
175- `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.
176 
177## Route-level debugging
178 
179If CLI behavior seems wrong, inspect the route-derived schema manifest instead of guessing.
180 
181Find routes by path:
182 
183```bash
184curl -fsS "$MASTRA_URL/api/system/api-schema" \
185  | jq '.routes[] | select(.path | contains("/memory"))'
186```
187 
188Inspect one route:
189 
190```bash
191curl -fsS "$MASTRA_URL/api/system/api-schema" \
192  | jq '.routes[] | select(.method == "POST" and .path == "/tools/:toolId/execute") | {pathParamSchema, queryParamSchema, bodySchema, responseShape}'
193```
194 
195## Known notes
196 
197- Tool and MCP tool execution accept raw tool input; explicit `{ "data": ... }` also works.
198- Workflow resume only works for suspended workflow runs.
199- Working memory update requires the agent's memory to have working memory enabled.
200- Empty lists may simply mean the server has no matching stored data yet.
201- `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.
202