Mechasmmechasm logoMechasmbeta
Back to Docs

Getting Started with the Mechasm CLI

Install the Mechasm CLI, approve project access, and run a hosted test.

Use the Mechasm CLI to manage projects, tests, and runs from a terminal or CI job.

Install and sign in

Use Node.js 22 or newer. Install the CLI globally:

npm install -g @mechasm/cli

Check the installation and sign in:

mechasm --version
mechasm login
mechasm doctor

doctor checks the CLI version, API connection, credentials, and local service. Sign in before running it; a stopped service is informational unless you use local-app runs.

Then sign in and list projects this device can access:

mechasm login
mechasm whoami
mechasm projects list

Login opens a browser approval page. Choose the project access this device needs. The CLI does not choose a default project; pass its ID with --project PROJECT_ID when you create tests, start runs, manage variables, or configure a local app.

If your workspace uses a specific Mechasm API address, use the address provided for your workspace with --api-url API_URL.

Create a project

To create a project, approve project creation in a team during login, then use:

mechasm teams list
mechasm projects create --name "Store QA" --url https://app.example.com --team TEAM_ID

Replace TEAM_ID and the example app URL with your values. --team is optional when exactly one team is approved. Use the project ID returned by this command in later examples. See Authentication & Permissions and Teams & Projects.

Run a first test

mechasm tests create --project PROJECT_ID --name "Home page" --prompt "Open the home page and check that it loads." --wait --json

For a multi-step flow, keep the prompt in Markdown so steps and expected outcomes are easy to review:

# Sign in
1. Open the sign-in page.
2. Enter the test account credentials.
3. Submit the form.

## Check
- Confirm the account dashboard appears.
- Confirm no error message is visible.

Save that text as prompt.md and pass --prompt-file prompt.md. Use --json when another command or script needs the result. For log streaming, save the latest cursor and pass it back with --after CURSOR after reconnecting; see Runs, Logs & Artifacts.

Replace PROJECT_ID with an ID from mechasm projects list or the create-project response. The command creates a test, starts generation and a run, and returns test and run IDs. --wait waits for the result; omit it to return sooner. See Tests and Runs, Logs & Artifacts.

Test a local app

If your app runs on your computer, start the CLI service and register the app’s address and ports:

mechasm service start
mechasm local register --project PROJECT_ID --url http://localhost:3000 --ports 3000,8080

Replace the project ID and ports with the ones your app uses. See Local Apps & Devices.