Back to Docs

CLI Runs, Logs & Artifacts

Wait for runs, resume log streams, stop work, and download videos or traces.

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

CodeMeaning
0Command succeeded.
1API or internal error.
2Invalid command or arguments.
3Authentication required or invalid.
4Permission denied.
5Run failed or was stopped.
130Wait was interrupted.