@monitodev/cli

The Monito CLI — manage projects, test scenarios, and runs from your terminal. Built for both humans and AI agents: every command supports --json, with data on stdout and human text on stderr.

Full docs: https://www.monito.dev/docs

Install

npm install -g @monitodev/cli
# or: pnpm add -g @monitodev/cli  ·  yarn global add @monitodev/cli  ·  bun add -g @monitodev/cli

This installs the monito command:

monito --version

Authenticate

monito auth login          # opens the browser to authenticate
monito auth status         # show current auth status
monito auth token          # print the current session token for scripts

Usage

monito project list                     # list projects
monito project run <project-id>         # run a project's scenarios
monito run view <run-id>                # inspect a run
monito session events <id> --type network
monito credits                          # show credit balance

Add --json to any command for machine-readable output:

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

Configuration

Credentials live at $XDG_CONFIG_HOME/monito/config.json (defaults to ~/.config/monito/). Environment variables override stored config:

• MONITO_TOKEN — auth token (takes priority over the config file)
• MONITO_HOST — API host (defaults to https://www.monito.dev)

monito config path
monito config set host https://your-instance.example.com

Commands

auth · ci · project · scenario · run · session · discovery · credits · config · schema

Run monito <command> --help for details, or see the documentation.

For AI agents

The CLI is designed to be driven by agents without a human in the loop.

Let an AI agent set up GitHub Actions

After two one-time browser sign-ins, an AI coding agent can configure the entire Monito CI integration. The agent discovers the project and repository, registers the exact repository and workflow binding, generates the workflow, and verifies GitHub's short-lived OIDC authentication. No Monito repository secret or API key is required.

monito auth login
gh auth login

Then give the agent the project name or ID. For a blocking production-deployment check, it should run:

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 .github/workflows/monito.yml and authorizes only the selected project, repository ID, owner ID, workflow ref, triggers, and environment. The generated job requests a short-lived GitHub OIDC token at runtime; the CLI keeps it in memory and never prints or persists it. --remote-auth dispatches and waits for an exactly correlated auth-only job without running scenarios or spending credits. The operation is idempotent, skips fork pull requests, and refuses to overwrite a workflow it does not own.

After static verification, the agent can commit and push .github/workflows/monito.yml using the repository's normal Git workflow. The CLI deliberately does not create commits or push code.

Once the workflow is on the repository's default branch, the agent can dispatch it to prove the integration works end to end. This spends Monito credits, so it requires a second explicit confirmation:

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

The generated workflow adds a concise GitHub job summary with scenario results and links. Recent-run listings omit large logs by default; request them only when needed:

monito run list --project <project-id> --json
monito run list --project <project-id> --include-logs --json

To remove CI, review the cleanup plan before approving it. Cleanup deletes only the exact Monito-owned binding and deterministic legacy credentials; unrelated keys are preserved for manual review.

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

Long-lived API-key authentication remains an explicit compatibility option with --auth api-key. Use it only for runners that cannot issue GitHub OIDC tokens. The lower-level monito auth create-key command returns the new key and should not be used by an agent unless the user explicitly requests that credential flow.

Use --execution webhook --trigger deployment with the same plan / apply / verify sequence for asynchronous post-deploy triggers. CLI 4 retains --mode github-actions and --mode deploy-webhook as deprecated aliases. Rotating an existing webhook credential additionally requires --rotate.

If webhook rotation succeeds but GitHub rejects a secret update, the CLI stores the new values in a mode-0600 recovery file and returns only its path. An agent should report that path without reading the file.

JSON in, JSON out. Machine-readable JSON goes to stdout; human/progress text goes to stderr. JSON mode turns on automatically when output is piped (stdout is not a TTY), so agents never have to remember a flag. You can also force it:

monito project list                 # piped → JSON automatically
monito project list --json          # explicit flag (global or per-command)
MONITO_JSON=1 monito project list    # via env var

Errors are structured. Every failure prints a typed envelope to stdout (in JSON mode) and sets a stable exit code — no string matching required:

{ "error": { "code": "auth", "message": "API error: Unauthorized" } }

| Exit | Meaning | | ---: | ---------------------------------------------------------- | | 0 | success | | 1 | command ran, but the test result failed | | 2 | auth — not authenticated / token expired | | 3 | not_found | | 4 | validation — bad input/arguments | | 5 | insufficient_credits | | 6 | timeout — run didn't finish in time | | 7 | network / server / unknown | | 8 | conflict — existing local state is not safe to overwrite |

Long-running runs. scenario run, project run, and project discover block until the run completes (so you get the result synchronously). Tune or escape the wait:

monito scenario run <id> --timeout 300000 --interval 5000   # ms
monito scenario run <id> --no-wait                          # return immediately

On timeout the run keeps going server-side; the error envelope includes the handle so you can resume:

{
  "error": { "code": "timeout", "message": "..." },
  "runId": "run_123",
  "status": "running"
}

monito run view run_123 --json     # poll it yourself

Self-describing. monito schema dumps the full command tree, options, error codes, and exit codes as JSON — point an agent at it to discover the surface:

monito schema | jq '.commands[].name'