---
name: com-verify-run
description: "Start and monitor Composal Verify browser sweeps from the CLI or MCP without computer use. Use for manual, Change, pull request, or cron runs against an environment, including a URL-only target with no repository."
---

# Run Composal Verify

Use Verify's CLI or MCP tools to launch remote browser agents. A run needs an
environment revision and immutable scenario pack. A repository and Change are
optional for manual and cron runs. Use `com-verifier-setup` when the target or
scenario pack has not been prepared, or `com-uat-plan` when acceptance intent is
still missing.

## Discover and prepare

Use `com verify --help` or call hosted MCP `verify_setup` to identify the
organization and current schemas. The local MCP groups the same core workflow
under `verify_environments`, `verify_scenarios`, `verify_sweeps`, and
`verify_schedules`. The hosted MCP exposes API operations named for their HTTP
method and path, such as `verify_post_sweeps_plan`.

List environments and packs before creating duplicates:

```sh
com verify environments list --org <org> --json
com verify scenarios list --org <org> --json
```

For an already running app, register its URL once. Use the actual environment
revision ID returned by `environments get`; do not substitute the environment ID
or digest. The URL must be reachable from remote browser agents. A local host
requires an accessible preview or tunnel.

```sh
com verify environments create --org <org> --slug <slug> --name '<name>' --target-url https://app.example.com --target-kind staging --idempotency-key <stable-key> --json
com verify environments get <environment-id> --org <org> --json
com verify scenarios import --org <org> --file .composal/verify/verify-scenarios.json --dry-run --json
com verify scenarios import --org <org> --file .composal/verify/verify-scenarios.json --idempotency-key <stable-key> --json
```

Pass `--repo <repo>` only when the environment or pack belongs to it or when
planning against a Change or pull request. Keep persona passwords, tokens and
TOTP seeds out of arguments and output. Bind existing organization Secret IDs
through `verify_test_accounts` in local MCP, or feed write-only values through
`com verify accounts set --from-stdin`. Hosted MCP provides credential tools;
never put raw values in a chat or tool argument visible to others.

## Plan and launch

Plan first and read its selected scenarios, exclusions, uncertainty and budget.
For a manual run, omit `--repo`, `--change` and `--pull-request` when none applies:

```sh
com verify sweeps plan --org <org> --environment-revision <revision-id> --scenario-pack <pack-id> --json
com verify sweeps run --org <org> --impact-plan <plan-id> --plan-digest <digest> --concurrency 4 --max-seconds 600 --idempotency-key <stable-key> --json
```

For a Change or pull request, add `--repo <repo>` to both commands and add
`--change '#123'` or `--pull-request <reference>` to the plan. In local MCP,
call `verify_sweeps` with `action: plan`, `organization`,
`environment_revision`, and `scenario_pack`; then call it with `action: run`,
`impact_plan`, `plan_digest`, and `idempotency_key`. The hosted MCP equivalents
are `verify_post_sweeps_plan` and `verify_post_sweeps`. Use returned IDs and
digests verbatim. Reuse the launch key after an uncertain response; use a new
key only for a deliberately new run. The launch returns a queued sweep while
remote capacity is acquired. It does not need a local browser session.

## Monitor and report

Return the live link `https://composal.ai/<org>/verify/sweeps/<sweep-id>` promptly.
Inspect state, attempts, findings, evidence and cleanup through tools:

```sh
com verify sweeps get <sweep-id> --org <org> --json
com verify sweeps watch <sweep-id> --org <org> --timeout-seconds 600 --json
com verify sweeps events <sweep-id> --org <org> --json
com verify evidence list --org <org> --sweep <sweep-id> --json
com verify findings list --org <org> --json
```

The local MCP uses `verify_sweeps` (`get`, `events`, `metrics`),
`verify_evidence`, and `verify_findings`. Hosted MCP has matching `verify_get_*`
operations. Poll at a modest interval; terminal state and cleanup determine
whether the run actually finished. Report passed, failed, blocked and
inconclusive attempts separately, with evidence links and any cleanup work.

## Cron trigger

Inspect existing schedules before creating one. A new schedule starts future
runs at its next due time; it does not immediately launch a run.

```sh
com verify schedules list --org <org> --json
com verify schedules create --org <org> --name '<name>' --environment-revision <revision-id> --scenario-pack <pack-id> --cron '0 9 * * 1-5' --timezone America/Los_Angeles --concurrency 4 --max-seconds 600 --json
com verify schedules pause <schedule-id> --org <org> --json
com verify schedules resume <schedule-id> --org <org> --json
```

Local MCP uses `verify_schedules` with `list`, `create`, `pause`, or `resume`.
Hosted MCP uses `verify_get_schedules`, `verify_post_schedules`, and
`verify_patch_schedules_item`. Check the returned `next_run_at` and state.