Run mechasm --help for the supported commands and complete syntax:
| Group | Commands |
|---|---|
| Account | login, logout, whoami |
| Diagnostics | doctor |
| Teams and projects | teams list, projects list, projects create |
| Variables | variables list, variables set, variables unset |
| Tests | tests create, tests edit, tests list, tests get, tests run |
| Runs | runs status, runs get, runs wait, runs logs, runs stop, runs video, runs trace, runs variables |
| Local apps | local register, local list, local select, local ports set, local unregister |
| Service | service start, service stop, service status, service foreground |
| Updates | update |
Common options
| Option | Use |
|---|---|
--api-url URL | Set the Mechasm API address provided for your workspace. |
--token-stdin | Read a scoped access token from standard input. |
--project ID | Select the project for test, run, variable, or local-app operations. |
--team ID | Choose an approved team for project creation; optional when exactly one team is approved. |
--value-stdin / --value-file FILE | Supply a project variable value without placing it in a raw flag. |
--prompt TEXT / --prompt-file FILE | Supply a test prompt; use - as the file to read from standard input. |
--name NAME | Set a project name with projects create or a test name with tests create / tests edit. |
--tags LIST | Set test tags with tests create / tests edit. |
| `—enabled true | false` |
--offset N / --limit N | Page test results; offset starts at 0 and limit accepts 1–100. |
--idempotency-key KEY | Retry a mutation after an unknown result using the same key. |
--wait | Wait for generation or run completion. |
--follow / --after CURSOR | Follow run logs or resume from a saved cursor. |
--out FILE | Save a video or trace to a new local file. Existing files are not overwritten. |
--url URL / --ports LIST | Set a local app address and its approved ports. |
--device-name NAME / --no-browser | Name the device at login or print a manual approval link. |
--version | Print the installed CLI version. |
--json | Write machine-readable output to stdout; errors go to stderr. |
Troubleshooting
| Problem | What to check |
|---|---|
Permission denied | Run mechasm login again and approve the needed project action or team project-creation access. Your account must already have access to that project or team; ask the team owner if it is missing. |
| No teams listed | Sign in again and approve project creation for the needed team. Your account must already belong to the team; ask the team owner if it is missing. |
--project required | Copy the project ID from mechasm projects list; the CLI does not choose a default project. |
| Token and prompt input conflict | --token-stdin and --prompt-file - both read standard input. Use a prompt file or another input source. |
| Variable value and token input conflict | --value-stdin and --token-stdin share standard input; provide the variable using --value-file. |
| Local run cannot reach app | Confirm the app is running, the project address and full port list are correct, and the selected device is online with access to those ports. |
| Video or trace is not ready | Run mechasm runs status RUN_ID --project PROJECT_ID again, then retry the download when the artifact is available. |
| Mutation result is unknown | Repeat the same mutation with the same --idempotency-key KEY. |
For run exit codes and resumable logs, see Runs, Logs & Artifacts.
Upgrade
mechasm update prints the npm upgrade command. In an interactive non-JSON terminal, the CLI also checks npm at most once per day and prints the command when a newer version is available. CI, JSON output, and the long-running foreground service skip the notice. Set MECHASM_NO_UPDATE_NOTIFIER=1 to disable it.
Before upgrading, let local runs finish. If the CLI service is running, restart it after installation so it loads the new version:
mechasm service stop
mechasm service startPass the same --api-url to both commands for a custom API origin.
npm install -g @mechasm/cli@latest