# Verifier CLI reference Use the Composal CLI to configure verification targets, import scenarios, plan and launch browser runs, inspect evidence, and read grouped results. `com` is the CLI for Verify, shadow environments, deployment, MCP, authentication, and setup. It builds without jj and works in an ordinary project directory. The main installer provides only the Composal product CLI. Use `com verify --help` and `com verify --help` for the flags accepted by your installed version. Browser agents run remotely. Manual and scheduled verification need a project, an environment, and saved Scenarios; a repository is optional. ## Sign in [Install the CLI](/docs/quickstart), then select your organization. Verify must be enabled; configuring targets and launching runs requires administrator access. ```sh com login com whoami com context switch ``` ## Use the CLI from an agent Install the compact Composal skill in your project. It works in an ordinary folder, preserves local edits and other skills, and needs no authentication: ```sh com skills install --targets codex --dry-run --json com skills install --targets codex --json com skills list --json ``` `com skills setup` is equivalent. This writes `.agents/skills/composal/SKILL.md` and focused testing workflow references. Add `--with deploy` to also install the `com-deploy` deployment skill. Use `com skills install --help` for other agents, or read the same guide at [`/agent.md`](/agent.md). Read a focused workflow with `com skills get --topic qa`, `com skills get --topic scenarios`, or `com skills get --topic tests`. Read the guide bundled with your installed version, check authentication, then inspect the command you need. Discovery works without signing in: ```sh com agent-guide com auth check --json com context show --json com schema verify admin runs prepare com api list --namespace hosting --filter deployment --agent ``` `--json` works before or after subcommands and preserves existing success payloads. `--format json` is its equivalent. Failures are one JSON object with stable `code`, `status`, `message`, `retryable`, and suggested `next[].argv` arguments. Progress goes to stderr. `--agent` also disables prompts and wraps success in a versioned receipt: inspect its `data` for the resource's actual state. It returns at most 50 records per list/history collection by default and reports truncation in `meta`. Single reports retain all their findings and checks. JSON mode does not approve mutations. Use `list` for collections and `get` for individual resources: for example, `com app get`, `com service get`, `com deploy get`, and `com verify runs get`. Existing read spellings remain supported. CDN also accepts `list`, `upload`, and `delete`. Token, secret, and CDN metadata return JSON records in machine mode, so field selection works across these families. Explicit token creation and audited secret reads return credential values; keep those responses private. For headless authentication, supply `COMPOSAL_API_TOKEN` through the environment or save a token from a private file using `com auth login --token-stdin --json`. Machine login does not open a browser or prompt; complete `com login` in an interactive terminal when user action is needed. `com auth check --org --json` validates organization membership too. ```sh com --json app list --org com app list --org --agent --fields id,name --limit 10 com --cwd /work/project context link --app storefront --service web --env staging --json ``` `--fields` and `--limit` control read results locally; use server query/cursor/page options to fetch the next page. Pagination metadata is preserved. A truncated response is not a complete inventory. Empty pages report `fields_validated: false` in receipt metadata because no records are available to validate names against. Validate fields against a non-empty response or the response schema. `context link` saves non-secret deployment selectors in `.composal/deploy.toml`; explicit selectors override that profile. Use explicit `--org` per command for parallel tasks instead of switching shared account defaults. Use `com api describe ` to inspect the installed OpenAPI request and response schemas, then `com api request` with the same words when a dedicated workflow command is unavailable. It reuses normal CLI credentials, tenant resolution, and server authorization. Complex input supports `--body-file` and `--body-stdin`, keeping credentials out of command arguments. For long operations, preserve returned IDs and idempotency keys. Queued work is not completed work; a waiting timeout may leave the remote job running. Deployment JSONL streaming is an explicit alternative to a single JSON receipt. Remote exec, MCP serving, completions, and terminal dashboards have separate output contracts; use them without JSON/agent mode. `com agent-guide` contains full deployment, verification, pagination, and recovery examples. ## Register an environment Every new environment belongs to one project. Create staging and preview environments inside the same project when they test the same product. Project knowledge is shared across those environments; separate products belong in separate projects. An assigned environment cannot be moved to another project. List projects to find their slugs, then use `--project ` for the project itself and its nested resources: ```sh com verify admin projects list --org acme com verify admin projects get --org acme --project shop --json com verify admin project-environments list --org acme --project shop --json ``` Project slugs are preferred. Names and public IDs also work. `--id` remains available for compatibility on project commands and selects the individual record on nested commands, such as `project-runs get --project shop --id `. JSON retains both the project slug and stable ID. `com schema` maps route path parameters to their CLI flags in `api.path_parameter_flags`. Inspect existing targets before creating one. For an already-running app, register a URL reachable by remote browser agents: ```sh com verify environments list --org --json com verify environments create --org \ --project --slug staging --name 'Staging' \ --target-url https://app.example.com --target-kind staging \ --idempotency-key --json com verify environments get --org --json ``` Use `--project` with a CLI version that lists it in `com verify environments create --help`. Older callers that omit the project create a separate project for the new environment. Existing unassigned legacy environments need explicit adoption; they do not contribute project knowledge. Use the ready **environment revision ID** returned by `get` when planning a run. It differs from the environment ID and digest. For a managed shadow, follow [environment setup](/docs/verify#first-run). ## Manage project Scenarios A project owns its saved YAML Scenarios, Personas, Credentials and Environments. Each run snapshots the selected definitions and creates one ScenarioRun per scenario. Independent scenarios execute in parallel within organization limits. Shared account and TOTP locks queue conflicting journeys; adding concurrency does not create accounts. ```sh com verify scenarios download --org acme --project storefront --dir scenarios com verify scenarios lint scenarios com verify scenarios upload --dir scenarios --dry-run --json com verify scenarios upload --dir scenarios --json com verify scenarios run scenarios/home.yaml scenarios/profile.yaml --org acme --project storefront --environment Preview --wait --json com verify runs list --org acme --project storefront --json com verify runs get --org acme --project storefront --json ``` Download includes `project.yaml` for upload context. Upload validates all files and saves them atomically; lint checks the bundled schema offline. Run executes the files as written without saving them. When a file's `id`, `version`, Persona, and run definition match an active scenario in the selected project, its result appears in that scenario's history. New, edited, stale, or unmatched files keep separate run history. Upload edits first to include their runs in the saved scenario's history. The dashboard can run selected saved scenarios. YAML version 1 uses one Persona and prose steps/outcomes. Version 2 declares named actors, their Personas, and evidence ownership. Every actor must be available in the same project. A requirement for a distinct teammate needs a distinct working account. For a PR, enable the project's **PR Testing** settings and choose its repository, environment template and preview source. Verify reads the current source diff, selects relevant saved scenarios with recorded reasons, prepares one grouped run on an exact-commit preview, and publishes its results. Low-confidence scenarios remain explicitly untested. A missing match is not a passing browser result. Manual selection can run other saved scenarios from the PR page. ```sh com verify pull-requests run 45 --org acme --repo storefront --head-sha --idempotency-key --json com verify pull-requests get --org acme --json ``` The PR report links the grouped run and records each scenario's result and findings. Cleanup is reported separately: cleanup trouble does not change a passed product verdict into a failed product verdict. Failed assertions, missing prerequisites and untested requirements remain visible. Retrying an uncertain request uses the same idempotency key; deliberately rerunning uses a new key. ## Research and maintain product knowledge Use `com knowledge` to browse the same project documents as **Knowledge → Documents** in Verify. List across projects to find their names and IDs, or search within a project by its slug or ID. The API returns up to 50 recent matching documents; narrow large libraries with `--query`. ```bash com knowledge list --org acme com knowledge list --org acme --project customer-portal --query "invitations" com knowledge read vknowledge_... --org acme > invitations.md com knowledge read vknowledge_... --org acme --json > invitations.json com knowledge add --org acme --project customer-portal \ --title "Invitations and roles" --file invitations.md --json cat invitations.md | com knowledge add --org acme --project customer-portal \ --title "Invitations and roles" --from-stdin --json ``` `read` prints Markdown for research and local editing. `--json` includes the document's title, project, source, and `content_digest` under `document`. Capture that digest **before editing**, then submit the complete Markdown with it: ```bash com knowledge edit vknowledge_... --org acme --file invitations.md \ --expected-digest --json ``` Add `--title "Revised title"` to rename the document; omission keeps its current title. Editing also accepts `--from-stdin`. If someone changes the document, the API refuses the save. Read the new version and reconcile your local edits before retrying with its digest. Organization members can list and read; administrators can add and edit. Organization selection follows the checkout or configured context unless `--org` overrides it. Writes require nonempty UTF-8 Markdown of at most 200,000 characters. Store feature purpose, navigation, roles, prerequisites, expected behavior, observed evidence, and remaining gaps. Keep credentials and access-bearing URLs in Credentials. Future discovery and scenario runners receive relevant, bounded excerpts from their environment's project. Knowledge guides navigation and reproduction; authored scenario actions and assertions still decide the result. See [product knowledge](/docs/verify#product-knowledge) for discovery and review behavior. ## Grouped runs Prepare and run saved project Scenarios in the dashboard, or use `com verify scenarios run` for YAML files. Each grouped Run reports individual scenario results and cleanup separately. ## Administer Verify resources `com verify admin` provides full access to the public Verify and project APIs, including operations kept outside the hosted MCP. Use `com verify scenarios` for YAML and `com verify runs` for grouped execution. Account and environment commands remain available. Use the normal organization selection and API token; Rails enforces membership, administrator permissions, feature access, version checks and mutation budgets. ```sh com verify admin --help com verify admin project-credentials help com verify admin network-connections help com verify admin project-personas help com verify admin network-connections create --org \ --body-file /private/network.json --json com verify admin project-credentials create --org --project '' \ --body-file /private/project-credential.json --json com verify admin project-personas update --org \ --project '' --id \ --body-file /private/persona.json --json com verify admin evidence download --org --id \ --output-file recording.webm --json ``` Request files contain the same JSON objects accepted by the public API. Keep them private and outside source control. `--body-file` and `--body-stdin` accept one JSON object and cannot be combined with `--set` or another body source. `--idempotency-key` sends the stable key as an HTTP header. Downloads preserve binary bytes, save to a new file and refuse to overwrite existing files. Project and environment names resolve within the selected organization and project. Ambiguous names require a public ID. Other identifiers are returned IDs; `help` lists additional selectors such as `--path persona=` or `--env `. This command group requires a CLI release containing `verify admin`; check your installed command help before using it. ## Verify a pull request or supply its CI preview Configure the connected repository's saved project Scenarios and preview source in **Verify → Integrations → GitHub**. The [Source Control guide](/docs/verify/source-control) covers automatic updates, Composal preview deployment, GitHub and GitLab preview discovery, and CI-owned previews. Check that your API and CLI support `pull-requests` before using these commands. ```sh com verify pull-requests run 45 --org --repo \ --idempotency-key --json com verify pull-requests get --org --json ``` For **Preview supplied by CI**, deploy the exact PR head and prepare a Verify preview environment for that organization and repository. Once the environment is ready, hand it off: ```sh com verify pull-requests preview 45 --org --repo \ --head-sha \ --environment --json ``` The `run` response includes the stable PR `id` and `requested_run_id`. PR history contains each request's selection, status, and grouped `run_id` once prepared. Read that Run with `com verify runs get --org --project ` and inspect per-scenario evidence. Submission confirms that the request was accepted; check the eventual outcome before treating a CI job as a passed verification. In CI, add `--head-sha ` to `pull-requests run` so a stale workflow cannot request coverage for a newer commit. CI supplies its Composal token through `COMPOSAL_API_TOKEN`, with `--org` and `--repo` explicitly set. See the guide for [CLI CI steps](/docs/verify/source-control/github#cli-ci), [the GitHub Action](/docs/verify/source-control/github#github-action), and publication status. ## Inspect results and evidence ```sh com verify runs get --org acme --project storefront --json com verify evidence list --org acme --scenario-run --json com verify findings list --org acme --project storefront --json com verify findings list --org acme --project storefront --source deep_scan --run --json com verify deep-scan findings --org acme --json com verify deep-scan findings --org acme --prompt com verify findings update --org acme --status dismissed ``` Open the source Run for live progress, recordings and per-scenario evidence. Product outcomes and cleanup have separate states. Pack and cron sweep interfaces are retired. For runner setup, VM and sandbox labels, and custom images, read the [GitHub Actions runner guide](/docs/github-actions-runners). ## Deploy and operate verification targets ```sh com deploy create --app --service web --env production --watch com deploy logs --app --task web com docker setup --registry registry.composal.ai com hub login --registry registry.composal.ai com hub push --org --repo --tag --registry registry.composal.ai ``` See [hosting](/docs/hosting), [Composal registry](/docs/registry), and [Managed OpenTelemetry](/docs/managed-otel) for the runtime and observability workflows that support your targets. ## Release notes Run `com --version` to inspect your installed version. Read the [CLI changelog](/docs/cli/changelog) for versioned release notes.