Use the CLI from an Agent Workflow

Keep agent requests short and specific. Name the project, target URL, test goal, and any limits. Use Markdown for multi-step prompts.

# Check account sign-in

Project: PROJECT_ID
Target: https://staging.example.com/sign-in

1. Open the sign-in page.
2. Sign in with the project's configured test account.
3. Confirm the account dashboard appears.

Do not change account settings or create data outside this test account.

Save the prompt as prompt.md and pass it to the CLI:

mechasm tests create --project PROJECT_ID --name "Sign-in" --prompt-file prompt.md --wait --json

Use explicit project and test IDs in later commands. The CLI does not choose a default project. --json writes machine-readable output to stdout; errors go to stderr. Store returned runId and testId values in workflow state rather than parsing terminal prose.

To follow logs, save the latest cursor and resume from it after a disconnect:

mechasm runs logs RUN_ID --project PROJECT_ID --follow --json
mechasm runs logs RUN_ID --project PROJECT_ID --after CURSOR --follow --json

Failed or stopped runs exit with code 5; invalid arguments exit 2, authentication failures 3, and permission denials 4. The optional npm update notice only runs in interactive non-JSON sessions; CI skips it. See Runs, Logs & Artifacts for artifact downloads and the full exit-code list.