AI Agent Usage

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. Check results
monito run view <run-id> --json
 
# 4. If failed, inspect the debug session
monito session view <session-id> --json
 
# 5. Get network events for debugging
monito session events <session-id> --type network --json

Claude Code Integration

When using Monito CLI with Claude Code, the AI agent can:

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

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