Verifier CLI reference

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 <command> --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, then select your organization. Verify must be enabled; configuring targets and launching runs requires administrator access.

com login
com whoami
com context switch <org>

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:

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. 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:

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 <org> --json validates organization membership too.

com --json app list --org <org>
com app list --org <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 <namespace> <resource> <action> 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 <slug> for the project itself and its nested resources:

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 <run-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:

com verify environments list --org <org> --json
com verify environments create --org <org> \
  --project <project-slug> --slug staging --name 'Staging' \
  --target-url https://app.example.com --target-kind staging \
  --idempotency-key <environment-key> --json
com verify environments get <environment-id> --org <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.

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.

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 <run-id> --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.

com verify pull-requests run 45 --org acme --repo storefront --head-sha <commit-sha> --idempotency-key <stable-key> --json
com verify pull-requests get <request-id> --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.

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:

com knowledge edit vknowledge_... --org acme --file invitations.md \
  --expected-digest <content_digest-from-read> --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 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.

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 <org> \
  --body-file /private/network.json --json
com verify admin project-credentials create --org <org> --project '<project name>' \
  --body-file /private/project-credential.json --json
com verify admin project-personas update --org <org> \
  --project '<project name>' --id <persona-id> \
  --body-file /private/persona.json --json
com verify admin evidence download --org <org> --id <evidence-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=<persona> or --env <environment-id>. 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 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.

com verify pull-requests run 45 --org <org> --repo <repo> \
  --idempotency-key <stable-request-key> --json
com verify pull-requests get <returned-pr-id> --org <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:

com verify pull-requests preview 45 --org <org> --repo <repo> \
  --head-sha <full-deployed-pr-head-sha> \
  --environment <verify-preview-slug> --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 <run-id> --org <org> --project <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 <full-deployed-pr-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, the GitHub Action, and publication status.

Inspect results and evidence

com verify runs get <run-id> --org acme --project storefront --json
com verify evidence list --org acme --scenario-run <scenario-run-id> --json
com verify findings list --org acme --project storefront --json
com verify findings list --org acme --project storefront --source deep_scan --run <scan-id> --json
com verify deep-scan findings <scan-id> --org acme --json
com verify deep-scan findings <scan-id> --org acme --prompt
com verify findings update <finding-id> --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.

Deploy and operate verification targets

com deploy create --app <app> --service web --env production --watch
com deploy logs --app <app> <allocation-id> --task web
com docker setup --registry registry.composal.ai
com hub login --registry registry.composal.ai
com hub push <image> --org <org> --repo <item> --tag <tag> --registry registry.composal.ai

See hosting, Composal registry, and Managed OpenTelemetry for the runtime and observability workflows that support your targets.

Release notes

Run com --version to inspect your installed version. Read the CLI changelog for versioned release notes.