AI Agent Usage

One-off verification

Prefer monito check <url> "<what should happen>" --json for one change, using a deployed URL or HTTP localhost such as http://localhost:3000/signup. Localhost opens a built-in tunnel; keep the CLI and dev server running until the verdict. It waits for a compact verdict with a report link and stays out of saved tests until monito check save <checkId> --name "Test name". On timeout, resume a deployed check with monito run wait <runId> --json. A local CLI timeout closes the tunnel; see local checks for limits and billing.

For previews with changing hostnames, add --project <projectId> (MCP: projectId) to keep checks in the existing project. For retries after uncertain network responses, reuse an explicit --request-id <id> (MCP/API: requestId); each invocation otherwise generates a new ID.

Setup guides: Claude Code, Cursor, Codex. The default MCP tools support checking, reading evidence and saving tests; opt into all for CI setup and the full catalog.

MCP or CLI?

Monito gives agents two interfaces for checking changes and reading evidence:

MCP server for agents in Claude, Claude Code, Cursor, VS Code, ChatGPT and other MCP clients. The agent calls typed tools such as run_scenario and get_run, and you connect it once with the URL https://www.monito.dev/api/mcp.
CLI for scripts, CI jobs and agents that work through a shell. Every command supports --json, and exit codes carry the verdict.

Prefer MCP when your agent runs in an MCP client: the hosted server needs no CLI installation, returns structured results, and can provide screenshots. Localhost checks require the local stdio server (monito mcp) or monito check; the hosted server rejects localhost. Use the CLI for automation that runs without an agent.

The rest of this guide covers the CLI. The CI setup below is also available as MCP tools (ci_plan, ci_apply, ci_verify, ci_cleanup) on the local MCP server.

Overview

The Monito CLI is designed for AI agent consumption. Every command supports --json for structured output, and data is cleanly separated from human text (stdout vs stderr).

Let the agent configure CI

An AI coding agent can set up Monito GitHub Actions from start to finish after you complete the two one-time browser sign-ins:

monito auth login
gh auth login

Then prompt the agent with the repository and Monito project context:

Set up Monito GitHub Actions for this repository using the Storefront project. Run the plan first, then apply and verify it. Do not expose credentials.

For a blocking check after a successful production deployment, the agent should use:

monito ci plan --execution blocking --auth oidc --trigger deployment \
  --environment Production --project "Storefront" --json
monito ci apply --execution blocking --auth oidc --trigger deployment \
  --environment Production --project "Storefront" --yes --json
monito ci verify --execution blocking --auth oidc --trigger deployment \
  --environment Production --project "Storefront" --remote-auth --json

plan is read-only. apply writes the workflow and registers the exact project, repository ID, owner ID, workflow ref, triggers, and environment that Monito may trust. The generated job exchanges GitHub's short-lived OIDC token in memory; it does not create, print, or store a Monito API key. --remote-auth runs an auth-only workflow, waits for its exact correlated result, and spends no Monito credits. The commands are idempotent, return versioned JSON, skip fork pull requests, and provide structured blockers and next actions.

After static verification, the agent can commit and push .github/workflows/monito.yml through the repository's normal Git workflow. The Monito CLI never commits or pushes code itself.

Do not use monito auth create-key --json for agent-driven CI setup because that lower-level command intentionally returns the new key. OIDC is the secretless path. Use --auth api-key only when the user explicitly requires compatibility with a runner that cannot use GitHub OIDC.

Once the generated workflow is on the repository's default branch, the agent can optionally dispatch a real run:

monito ci verify --execution blocking --auth oidc --trigger deployment \
  --environment Production --project "Storefront" --run --yes --json

This spends Monito credits, so the CLI requires explicit confirmation.

CLI 4 retains --mode github-actions and --mode deploy-webhook as deprecated aliases. Prefer --execution plus repeatable --trigger flags in agent automation.

To remove the integration, plan cleanup separately and inspect the exact operations before applying:

monito ci cleanup --execution blocking --auth oidc --trigger deployment \
  --environment Production --project "Storefront" --json
monito ci cleanup --execution blocking --auth oidc --trigger deployment \
  --environment Production --project "Storefront" --yes --json

Cleanup preserves unknown keys for manual review. It must run only after a replacement authentication path has passed --remote-auth and the user has approved removal.

Authentication

For normal CLI use, authenticate once in the browser:

monito auth login

For an existing headless environment, you can instead set the MONITO_TOKEN environment variable:

export MONITO_TOKEN=$(monito auth token)

Or retrieve a token programmatically:

TOKEN=$(monito auth token)

Structured Output

Use --json to get machine-readable output:

# List projects
monito project list --json

# Get run results
monito run view <id> --json

# Get session events
monito session events <id> --type network --json

Parsing with jq

# Get project IDs
monito project list --json | jq '.projects[].id'

# Get compact failed runs for one project
monito run list --project <project-id> --json | jq '.runs[] | select(.status == "failed")'

# Include large logs only for focused debugging
monito run list --project <project-id> --include-logs --json

# Get bug report titles from a session
monito session view <id> --json | jq '.bugReports[].ticketTitle'

Workflow Example

A typical AI agent workflow:

# 1. List projects
monito project list --json

# 2. Run all scenarios for a project
monito project run <project-id> --json

# 3. Get the full failure diagnosis in one call:
#    run summary, verdict reason, bug reports, failed requests,
#    console errors, and screenshot refs
monito run view <run-id> --evidence --json

For deep dives beyond the evidence bundle, the granular session commands remain available:

# Inspect the full debug session
monito session view <session-id> --json

# Get network events for debugging
monito session events <session-id> --type network --json

Claude Code Integration

Connect the MCP server so Claude Code can run tests and read the results as tools:

claude mcp add --transport http monito https://www.monito.dev/api/mcp

Claude Code can also drive the CLI directly. In that case the agent can:

Run monito ci plan/apply/verify --auth oidc to configure CI without creating credentials
Run monito project list --json to discover available projects
Run monito scenario run <id> --json to execute tests
Parse the JSON output to understand test results
Use monito session events <id> --json to debug failures

The --json flag ensures all output is parseable, and exit codes indicate pass/fail status.

Retrying launches safely

Pass --request-id <id> to monito scenario run or monito project run (or requestId to the MCP run tools). Repeating the same ID returns the first launch instead of starting and charging again, so an agent can retry after a network error without spending credits twice.

On this page