Test create/edit commands that start a run, and tests run, return a runId and workspace runUrl. Use that ID for run operations. Every run command requires --project PROJECT_ID.
Check and wait
mechasm runs status RUN_ID --project PROJECT_ID --json
mechasm runs get RUN_ID --project PROJECT_ID --json
mechasm runs wait RUN_ID --project PROJECT_ID --json
runs status and runs get report the current run status and artifact availability. The optional runs wait command waits silently until completion, then returns the final result without displaying live logs. With --json, it returns one final JSON result. The --wait option on test create/edit/run commands uses the same waiting behavior. Use log following below to watch execution.
Status includes terminal and, while active, progress with a phase, message and phase start time when available. Failed runs include a customer-facing error message, category, failure phase when recorded, and suggestedNextStep. When no detailed cause was recorded, the response says so rather than inventing one. The run URL and artifact availability remain in the same response.
Status/get/wait commands exit with code 5 for failed or stopped runs. A user-stopped run is reported as failed with the reason Stopped by user. A run that recovers successfully can finish as passed even if earlier failed steps remain in its logs.
Follow or resume logs
mechasm runs logs RUN_ID --project PROJECT_ID --follow --json
mechasm runs logs RUN_ID --project PROJECT_ID --after CURSOR --follow --json
JSON follow mode writes each event and cursor checkpoint as a JSON line. Save the latest cursor and pass it with --after after a disconnect to resume. Keep the run ID and cursor in your workflow state.
After the stream finishes, use runs status RUN_ID --project PROJECT_ID --json to check the final result. Log streaming alone does not report pass/fail through its exit code; a closed stream or a failed step in the logs does not establish the final outcome.
Download evidence and read run variables
mechasm runs video RUN_ID --project PROJECT_ID --out run.webm
mechasm runs trace RUN_ID --project PROJECT_ID --out run-trace.zip
mechasm runs variables RUN_ID --project PROJECT_ID --json
Video and trace files are written to a new local path; existing files are not overwritten. They may become available after the run result. If an artifact is not ready, check runs status again and retry the download when it is available.
Use trace screenshots/page snapshots, actions and errors to compare the observed behavior with the intended result; use video as supporting evidence. Do not infer success from the existence of an artifact. Accept genuine failures. Clarify an ambiguous prompt or an assumption introduced by the agent without weakening the user’s requirement, then inspect the new run. If assets are unavailable or cannot be inspected, report that limitation. See Agent Workflows for the full review sequence.
Stop an active run
mechasm runs stop RUN_ID --project PROJECT_ID
Stopping an active run releases its place in the run queue. The run ends as failed with the reason Stopped by user; runs wait exits with code 5.
Let Mechasm’s healer work while a run is active: failed steps or unexpected pages can be corrected automatically. Wait for the overall final result rather than stopping after an arbitrary time or individual failed action. Stop when the user requests it, or when you deliberately need to change the prompt before continuing.
Exit codes
| Code | Meaning |
|---|---|
0 | Command succeeded. |
1 | API or internal error. |
2 | Invalid command or arguments. |
3 | Authentication required or invalid. |
4 | Permission denied. |
5 | Run failed or was stopped. |
130 | Wait was interrupted. |