A script needs to know whether work succeeded and what to do when it did not. mg provides an exit status plus a structured result. Use both; a JSON file can describe a failure just as well as a success.
Read one JSON result
mg version --json
mg help --json
--json writes one envelope on stdout. On success it contains ok: true, command, exit_code: 0 and result. Version data lives under result, including version, revision, go_version and platform. Help data includes the available commands and flags, so a consumer can inspect this build’s capabilities.
On failure, ok is false and error describes the problem with fields such as kind, message, an optional id and next steps. A human-readable diagnostic can still appear on stderr. Capture stdout separately; redirecting 2>&1 into a JSON file mixes the two streams.
if mg version --json > mg-result.json; then
printf 'Version captured in mg-result.json\n'
else
code=$?
printf 'mg exited %s; inspect mg-result.json and stderr\n' "$code" >&2
fi
Ask for agent guidance
mg help --agent
mg version --json --agent
In text mode, --agent adds an AGENT_PROMPT_BEGIN / AGENT_PROMPT_END block on stderr. Combined with JSON, the executable places guidance under agent_prompt in the same envelope. MG_AGENT=1 also opts in. The prompt offers next steps; it does not execute them or authorize writing files.
The source launcher can fail before the executable starts. Its JSON error still reports exit 3, but consumers must tolerate absent agent_prompt and result fields.
Keep failures meaningful
| Exit | Meaning | Response |
|---|---|---|
| 0 | Success | Consume the result |
| 1 | Refusal, including generated-file drift | Inspect the input or listed files |
| 2 | Incorrect command or arguments | Read the suggested help |
| 3 | Could not measure | Restore the missing tool, input or access |
| 101 | Internal fault | Save the diagnostic and mg version |
| 128+n | Stopped by signal n | Inspect why the process was interrupted |
An unavailable check is not a passing check. In a CI step, preserve a nonzero status instead of swallowing it with an unconditional success command. For generation, use mg gen examples --check --json after confirming that command is available.
Try a safe failure
mg hlep --json
Expect exit 2, a failure envelope on stdout and correction guidance on stderr. Compare it with successful mg help --json. Your consumer should distinguish them without parsing English prose. Return to the course overview for the complete workflow.