@mechasm/cli 0.1.1 → 0.1.3

package/AGENT_GUIDE.md

@@ -5,11 +5,25 @@ Use Node.js 22 or newer. Install `@mechasm/cli`, sign in with `mechasm login`, t
 Keep each test request in Markdown. Name the project ID, target URL, expected result, and limits. Reuse configured test accounts; do not ask agents to expose credentials or change data outside the named test scope.
 
 ```sh
-mechasm tests create --project PROJECT_ID --name "Sign-in" --prompt-file prompt.md --wait --json
+mechasm tests create --project PROJECT_ID --name "Sign-in" --prompt-file prompt.md --json
 ```
 
-Use explicit project, test, and run IDs. Do not assume a default project. Use `--json` for scripts; stdout contains JSON and errors go to stderr. Save run IDs and log cursors in workflow state. Resume logs with `--after CURSOR` after reconnecting.
+Save the returned `testId`, `runId` and `runUrl`. Follow execution using the run ID:
 
-Exit code `5` means the run failed or was stopped. Code `2` means invalid arguments, `3` authentication failed, and `4` permission was denied. The optional npm update notice runs only in interactive non-JSON sessions; CI skips it.
+```sh
+mechasm runs logs RUN_ID --project PROJECT_ID --follow --json
+```
+
+When the stream finishes, check the final result:
+
+```sh
+mechasm runs status RUN_ID --project PROJECT_ID --json
+```
+
+Log streaming alone does not report pass/fail through its exit code. Do not infer success from a closed stream or an individual log line. For scripts that only need the final result, `--wait` on create/edit/run or `runs wait` waits silently and returns the final result without displaying live logs. With `--json`, it returns one final JSON result.
+
+Use explicit project, test, and run IDs. Do not assume a default project. Use `--json` for scripts; stdout contains JSON and errors go to stderr. Log following emits JSON lines. Save run IDs and log cursors in workflow state. Resume logs with `--after CURSOR` after reconnecting.
+
+Exit code `5` from a status/get/wait command or a test command using `--wait` means the run failed or was stopped. Code `2` means invalid arguments, `3` authentication failed, and `4` permission was denied. The optional npm update notice runs only in interactive non-JSON sessions; CI skips it.
 
 See [CLI documentation](https://mechasm.ai/docs/mechasm-cli/getting-started) for full command details.

package/README.md

@@ -38,12 +38,24 @@ Pass project IDs explicitly to test, run, variable, and local-app commands. The
 ```sh
 mechasm teams list
 mechasm projects create --name "Store QA" --url https://app.example.com --team TEAM_ID
-mechasm tests create --project PROJECT_ID --name "Home page" --prompt "Open the home page and check that it loads." --wait --json
+mechasm tests create --project PROJECT_ID --name "Home page" --prompt "Open the home page and check that it loads." --json
 ```
 
 Replace `TEAM_ID`, `PROJECT_ID`, and the example URL with your values. `--team` is optional when exactly one team is approved. The project creation response contains the project ID to use in later commands.
 
-Commands that start a run return its `runId` and workspace `runUrl`. `--wait` waits for the final result. Failed or stopped runs exit with code 5.
+Commands that start a run return its `runId` and workspace `runUrl`. Use the returned run ID to follow execution:
+
+```sh
+mechasm runs logs RUN_ID --project PROJECT_ID --follow
+```
+
+After the log stream finishes, check the final result:
+
+```sh
+mechasm runs status RUN_ID --project PROJECT_ID --json
+```
+
+Log streaming alone does not report pass/fail through its exit code. Status/get commands return exit code 5 for failed or stopped runs. For scripts that only need the final result, add the optional `--wait` to create/edit/run, or use `runs wait`. Waiting is silent until completion and does not display live logs. With `--json`, it returns one final JSON result; failed or stopped runs exit with code 5.
 
 ## Manage variables safely
 

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@mechasm/cli",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Mechasm command line client",
+  "homepage": "https://mechasm.ai/docs/mechasm-cli/getting-started",
   "license": "SEE LICENSE IN LICENSE",
   "publishConfig": {
     "access": "public"

package/src/cli.js

@@ -60,14 +60,19 @@ Options:
   --idempotency-key KEY  Reuse key after an unknown mutation result
   --url URL           Project or local app URL
   --ports LIST        Comma-separated local ports
-  --wait              Wait for test generation or run completion; metadata-only operations return immediately
+  --wait              Wait silently for the final result; metadata-only edits return immediately
   --follow            Follow run logs until it finishes
   --after CURSOR      Resume run log history
   --out FILE          Save video or trace to a new file
   --json              JSON output on stdout; errors on stderr
 
-Commands that start a run return its workspace URL; plain output shows it as "View run".
+Commands that start a run return runId and runUrl; --wait delays output until completion.
+To watch progress, start without --wait, then use: mechasm runs logs RUN_ID --project ID --follow
+After following logs, use runs status to check the result. Log streaming alone does not report pass/fail via its exit code.
 No command opens a local public listener. Project IDs are required for test and run operations.
+
+Documentation: https://mechasm.ai/docs/mechasm-cli/getting-started
+Agent workflows: https://mechasm.ai/docs/mechasm-cli/agent-workflows
 `;
 const RUNNER_MANAGED_VARIABLES = new Set(['CI_TOKEN', 'RUN_WS_TOKEN', 'WS_AUTH_COOKIE']);