CLI | Composal

Built for agents

JSON output, versioned receipts, stable error codes, and the next command as argv

The same records as Verify

Scenarios, runs, evidence, findings, and knowledge are the ones your team sees in the dashboard

Safe in CI

Idempotency keys make retries safe, and the head SHA pins the exact commit

Give your agent the Composal skill

One command writes the skill into your project, with focused workflows your agent reads offline. It works in any folder and keeps your local edits.

Keep Scenarios next to your code

Download a project’s Scenarios as YAML, lint them offline, and upload every file atomically. Run files as written and wait for the grouped result.

a-tester-adds-and-renames-an-environment-then-archives-only-that-environment.yaml.yaml
a-tester-creates-a-scenario-and-sees-its-saved-instructions-after-reopening.yaml.yaml
a-tester-edits-a-scenario-and-sees-the-new-steps-without-changing-its-neighbor.yaml.yaml
a-tester-filters-environments-and-restores-the-saved-environment-after-clearing.yaml.yaml
a-tester-opens-a-completed-run-and-reviews-each-scenario-result-and-replay-evide.yaml.yaml
a-tester-opens-verify-and-navigates-between-a-project-and-its-overview.yaml.yaml
a-tester-prepares-discovery-with-a-project-environment-and-cancels-before-launch.yaml.yaml
a-tester-reviews-credential-setup-without-exposing-or-changing-credentials.yaml.yaml
a-tester-selects-two-scenarios-and-reviews-one-grouped-run-before-cancelling.yaml.yaml
a-tester-writes-and-edits-project-knowledge-then-archives-the-disposable-guide.yaml.yaml
no-cookie-popups-on-vex-website-and-docs.yaml.yaml

no-cookie-popups-on-vex-website-and-docs.yaml.yaml

# yaml-language-server: $schema=https://composal.ai/schema/verify/v1/scenario.json
$schema: https://composal.ai/schema/verify/v1/scenario.json
name: No cookie popups on Vex website and docs
persona: Signed-out visitor
allowed_actions: read_only
starting_conditions: Both public sites are reachable without signing in. Do not accept, reject, dismiss, or otherwise interact with cookie-consent controls; observation only.
steps:
  - Open https://composal.ai/ and wait for the initial page to finish rendering. Inspect the viewport, fixed overlays, banners, dialogs, and accessible page content for any cookie-consent, cookie-preference, privacy-consent, tracking-consent, or similar popup/banner.
  - Navigate to https://composal.ai/docs and wait for the initial page to finish rendering. Inspect the viewport, fixed overlays, banners, dialogs, and accessible page content for any cookie-consent, cookie-preference, privacy-consent, tracking-consent, or similar popup/banner.
outcomes:
  - No cookie popup, cookie banner, cookie-consent dialog, cookie-preference modal, or other tracking/privacy-consent prompt is visible or presented on https://composal.ai/.
  - No cookie popup, cookie banner, cookie-consent dialog, cookie-preference modal, or other tracking/privacy-consent prompt is visible or presented on https://composal.ai/docs.
  - Fail the scenario if any such prompt is detected on either site.

Read every answer as JSON

With --json or --agent, a failure is one object with a stable code, whether to retry, and the next command as argv. Agent mode never prompts.

Verify pull requests from CI

Request verification for the exact deployed head. A stale workflow is refused, and a retry with the same idempotency key is safe. Then read the grouped run, its evidence, and findings.

.github/workflows/verify.yml

- name: Request Composal verification
  env:
    VEX_API_TOKEN: ${{ secrets.COMPOSAL_TOKEN }}
  run: |
    com verify pull-requests run 45 \
      --org <org> --repo <repo> \
      --head-sha \
        ${{ github.event.pull_request.head.sha }} \
      --idempotency-key <key> --json

--head-shaRefuses a stale workflow before it requests a newer commit

--idempotency-keyRetrying an uncertain request reuses the key

Accepted is not passed. Read the outcome with com verify pull-requests get

Keep product knowledge current

Read, add, and edit your project’s knowledge as Markdown. Each edit carries the digest you read, so a concurrent change refuses the save instead of being overwritten.

What you get back

What the CLI returns

Every command answers in plain text for you, or one JSON object for your agent, with the same runs, findings, and evidence your team sees in Composal.

com · vex / composal

Run results · stdout

$ com verify scenarios run a-tester-*.yaml no-cookie-*.yaml --wait

Watch run verification_run_dXwVaxj561r2SAEKlNZQB3Mk: https://composal.ai/vex/verify/composal/runs/…

Queued run verification_run_dXwVaxj561r2SAEKlNZQB3Mk.

passed A tester adds and renames an environment then archives only that environment

passed A tester creates a scenario and sees its saved instructions after reopening

passed A tester edits a scenario and sees the new steps without changing its neighbor

passed A tester filters environments and restores the saved environment after clearing search

passed A tester opens a completed run and reviews each scenario result and replay evidence

passed A tester opens Verify and navigates between a project and its overview

passed A tester prepares Discovery with a project environment and cancels before launch

passed A tester reviews credential setup without exposing or changing credentials

passed A tester selects two scenarios and reviews one grouped run before cancelling

passed A tester writes and edits project knowledge then archives the disposable guide

blocked No cookie popups on Vex website and docs

error: run verification_run_dXwVaxj561r2SAEKlNZQB3Mk blocked; see https://composal.ai/vex/verify/composal/runs/…

$ echo $?

Grouped run details · agent receipt

$ com verify runs get verification_run_dXwVaxj561r2SAEKlNZQB3Mk --org vex --project composal --agent

{

"schema_version": 1,

"status": "ok",

"data": {

"run": {

"id": "verification_run_dXwVaxj561r2SAEKlNZQB3Mk",

"state": "terminal",

"outcome": "blocked",

"cleanup_state": <cleanup state>

"scenario_runs": [

{ "state": "passed", "scenario_snapshot": { "name": "A tester adds and renames an environment then archives only that environment"

… 9 more, each "passed"

{ "state": "blocked", "scenario_snapshot": { "name": "No cookie popups on Vex website and docs"

"failure_code": <code>, "evidence": [<items>], "finding_ids": [<ids>] }

"web_path": "/vex/verify/composal/runs/…"

"meta": { "cli_version": <version>, "truncated": false, "fields_validated": null }

}

Findings and evidence · JSON

$ com verify findings list --org vex --json

[{idstatusseverityconfidencetitlesafe_summaryoccurrence_countlast_seen_at}, …]

$ com verify evidence list --org vex --scenario-run <id> --json

[{idkindcontent_typebyte_sizechecksumredaction_statereadableretention_expires_at}, …]

Agent failure · one JSON object

$ com verify runs get <run-id> --agent

{ "schema_version": 1,

"status": "action_required",

"code": "AUTH_EXPIRED",

"message": "The Composal API returned HTTP 401.",

"retryable": false,

"user_action_required": true,

"next": [{ "argv": ["com", "login"] }]

}

Lint and upload · offline, atomic

$ com verify scenarios lint scenarios

… 10 more valid

valid scenarios/no-cookie-popups-on-vex-website-and-docs.yaml

11 valid, 0 invalid

$ com verify scenarios upload --dir scenarios --dry-run --org vex

… 10 more unchanged

unchanged scenarios/no-cookie-popups-on-vex-website-and-docs.yaml

0 to create, 0 to update, 11 unchanged, 0 refused

Dry run: nothing was saved.

What you can do with it

Fail CI on a failed run
com verify scenarios run --wait exits nonzero unless every Scenario passes, so the job fails on a failed or blocked run with no parsing.
Hand the next step to your agent
Each failure carries next[].argv. Your agent runs it, or tells you when the step needs you, such as signing in again.
Download the evidence
Save a Scenario’s recording, trace, or screenshot by its evidence ID. Downloads keep the bytes intact and never overwrite an existing file.
Keep only the fields you need
--fields and --limit trim a read before it reaches your agent, and meta says whether anything was cut.