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, 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 
15For local servers, `mastra api` defaults to `http://localhost:4111`:
16 
17```bash
18npx mastra api agent list
19```
20 
21For 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:
22 
23```bash
24npx mastra api --url $MASTRA_URL agent list
25```
26 
27Verify the server once with a cheap check before resource calls:
28 
29```bash
30MASTRA_URL="${MASTRA_URL:-http://localhost:4111}"
31curl -fsS "$MASTRA_URL/api/system/api-schema" >/dev/null
32```
33 
34If `$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.
35 
36For authenticated servers, pass repeatable headers:
37 
38```bash
39npx mastra api --url "$MASTRA_URL" --header "Authorization: Bearer $TOKEN" agent list
40```
41 
42## Decision flow
43 
441. Clear read-only request (`list X`, `latest X`, `get X`, `summarize recent X`): infer the resource and use the fast path first.
452. Mutating request (`create`, `update`, `delete`, `run`, `resume`, `execute`), unclear resource/action, failed fast path, or exact syntax requested: use narrow CLI discovery.
463. JSON input uncertain: use command-specific `--schema`.
474. Route behavior confusing: inspect `/api/system/api-schema`.
48 
49Start with these command groups when present; verify with `mastra api --help` if the group fails.
50 
51```text
52agent workflow tool mcp thread memory trace log score dataset experiment
53```
54 
55## Fast path for read-only requests
56 
57Use conventional `list`/`get` commands first. Keep pages small and pipe through `jq` immediately.
58 
59Latest item:
60 
61```bash
62npx mastra api <resource> list '{"page":0,"perPage":1}' \
63  | jq '.data[0]'
64```
65 
66Recent items:
67 
68```bash
69npx mastra api <resource> list '{"page":0,"perPage":10}' \
70  | jq '.data[]'
71```
72 
73When the shape is known, project only the fields needed for the task:
74 
75```bash
76npx mastra api <resource> list '{"page":0,"perPage":10}' \
77  | jq '.data[] | {id, name, createdAt, status}'
78```
79 
80Get details:
81 
82```bash
83npx mastra api <resource> get <id> \
84  | jq '.data'
85```
86 
87When the shape is known, project only the fields needed for the task:
88 
89```bash
90npx mastra api <resource> get <id> \
91  | jq '.data | {id, name, createdAt, status}'
92```
93 
94If a resource does not support the conventional shape, fall back to narrow `--help` for that resource/action.
95 
96## Output control
97 
98- Do not use unfiltered `--pretty` during exploration.
99- Always project list/get output with `jq` before reading details.
100- Use `perPage:1` for latest and `perPage:10` or less for recent lists.
101- If output is truncated or noisy, rerun with a narrower `jq` projection. Do not increase terminal output just to see more raw JSON.
102- Fetch full JSON only when the user asks for raw output or compact projections are insufficient.
103 
104## Fallback discovery
105 
106Use the narrowest discovery command that can answer the question. Example for traces:
107 
108```bash
109npx mastra api trace --help
110npx mastra api trace list --help
111npx mastra api trace list --schema
112```
113 
114Use top-level help only when the resource is unknown:
115 
116```bash
117npx mastra api --help
118```
119 
120Read `--schema` output as the contract:
121 
122- `command`: usage string
123- `examples`: known-good examples
124- `positionals`: required path/identity arguments
125- `input.required`: whether JSON input is required
126- `input.schema`: accepted CLI JSON input, including query/body fields
127- `schemas`: raw server route schemas for deeper debugging
128 
129## JSON and output contract
130 
131`mastra api` accepts at most one inline JSON object as input. Do not use stdin or files unless the user explicitly asks.
132 
133For non-GET routes, the CLI splits the one JSON object into query parameters and request body according to the server route schema.
134 
135Output envelopes:
136 
137```json
138{ "data": {} }
139{ "data": [], "page": { "total": 0, "page": 0, "perPage": 0, "hasMore": false } }
140{ "error": { "code": "...", "message": "...", "details": {} } }
141```
142 
143## Error handling
144 
145- `INVALID_JSON`: fix shell quoting; input must be one JSON object.
146- `MISSING_INPUT`: run the same command with `--schema` and supply required JSON.
147- `MISSING_ARGUMENT`: provide the positional shown by `--help` / `--schema`.
148- `HTTP_ERROR`: inspect `error.details`, then compare against `--schema` or route schema.
149- `REQUEST_TIMEOUT`: retry with larger `--timeout`, especially for workflow execution.
150- `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.
151 
152## Route-level debugging
153 
154If CLI behavior seems wrong, inspect the route-derived schema manifest instead of guessing.
155 
156Find routes by path:
157 
158```bash
159curl -fsS "$MASTRA_URL/api/system/api-schema" \
160  | jq '.routes[] | select(.path | contains("/memory"))'
161```
162 
163Inspect one route:
164 
165```bash
166curl -fsS "$MASTRA_URL/api/system/api-schema" \
167  | jq '.routes[] | select(.method == "POST" and .path == "/tools/:toolId/execute") | {pathParamSchema, queryParamSchema, bodySchema, responseShape}'
168```
169 
170## Known notes
171 
172- Tool and MCP tool execution accept raw tool input; explicit `{ "data": ... }` also works.
173- Workflow resume only works for suspended workflow runs.
174- Working memory update requires the agent's memory to have working memory enabled.
175- Empty lists may simply mean the server has no matching stored data yet.
176