Private beta CLI

Flock Synthetic CLI

Run synthetic UX reviews from a configured Flock runtime checkout and inspect the resulting artifacts.

These commands require runtime access, Node.js 24 or later, installed project dependencies, and the browser and model-provider setup supplied for your environment. Contact Flock to confirm access and setup requirements; this page is not a public package installation guide.

Evidence-backed by default

Read findings alongside their verification status and available evidence. A completed review can still include unverified observations; confidence alone is not proof of a defect.

Quickstart Recipes

From a configured runtime checkout, choose a run mode and replace the example URL with your target. The persona IDs below are included in the runtime catalog. Do not run commands until your environment and access are ready.

Copy/paste starter commands:

Single run

Use for a focused page review with one persona.

npm run tester -- \
  --url https://dashboard.example.com/signup \
  --persona novice-user \
  --goal "Create a trial account" \
  --goal-outcome-type onboarding \
  --success-signals '[{"type":"url_match","value":"**/welcome"}]'

Flow run

Use for a multi-step journey, with exploratory or scripted navigation.

npm run flow -- \
  --url https://dashboard.example.com \
  --persona skeptical-evaluator \
  --flow-mode roam \
  --max-steps 8 \
  --time-budget 300000 \
  --goal "Find pricing and compare plans"

Batch comparison

Use to review the same target with multiple personas and compare their results.

npm run batch -- \
  --url https://dashboard.example.com/signup \
  --personas novice-user,power-user,security-admin \
  --goal "Complete signup without support"

Shared Context Flags

These flags define what success means and the conditions under which runs execute. Think of this as the request shape shared by tester, flow, and batch.

Goal shape

Describe the user task and how success is measured.

--goal, --goal-outcome-type
--success-description, --success-criteria
--constraints
--success-signals (JSON array with type + value)

Scenario fixtures

Set reproducible test conditions and context.

--scenario-fixture (JSON object)
--scenario-seed, --scenario-scope
--scenario-template-id, --scenario-template-version
--scenario-overrides (JSON object)

Execution modes

Choose live capture or an artifact-based mode. Replay and hybrid modes require the corresponding prepared artifacts and runtime configuration.

--execution-mode live
--execution-mode artifact_replay
--execution-mode hybrid_first_capture
--flow-mode roam|scripted

Command Reference

Run these commands from your configured runtime checkout. Replace URL, persona, and run-directory placeholders with values from your environment.

Single persona run

Run one persona against one target URL and write a run artifact bundle.

npm run tester -- --url <https://...> --persona <persona-id>

Flow run (multi-step)

Run a multi-step journey, either exploratory or replayed from an existing flow file.

npm run flow -- --url <https://...> --persona <persona-id> --flow-mode roam

Batch run (persona comparison)

Compare outcomes across personas, or generate a population sample.

npm run batch -- --url <https://...> --personas <p1,p2,p3>

Render existing artifacts

Render shareable markdown reports from existing run and flow artifacts.

npm run render -- --run <runs/run_example>
npm run render:flow -- --run <runs/run_example>

Key Output Files

These abbreviated excerpts come from an internal replay evaluation of a synthetic checkout page. Omitted fields are not shown. The review completed with one unverified observation; completion does not establish that the observation is a confirmed defect.

output.json / flow.json

Structured findings for a page or flow. This output.json excerpt retains the recorded evidence references and verification status; referenced image bytes are not included.

{
  "schema_version": "2.0.0",
  "persona_id": "novice-user",
  "page_url": "https://example.test/checkout",
  "perception_scope": "screenshot_only",
  "friction_events": [
    {
      "event_id": "event-1",
      "severity": 2,
      "summary": "The Checkout button is very low-contrast, so the main action is hard to read at a glance.",
      "confidence": 0.5,
      "evidence": {
        "screenshot_ref": "artifacts/screenshot.png",
        "page_url": "https://example.test/checkout",
        "timestamp": null,
        "dom_ref": null,
        "har_ref": null,
        "location": {
          "region": "center",
          "bbox": null
        }
      },
      "verification": {
        "status": "unverified",
        "failure_tags": [
          "webmarker_unavailable",
          "dom_snapshot_unavailable"
        ]
      }
    }
  ]
}

summary.json / summary.md

Batch-level results across personas. This summary.json excerpt preserves the recorded completion and verification counts.

{
  "schema_version": "1.0.0",
  "status": "completed",
  "batch_outcome": "succeeded",
  "runs_completed": 1,
  "runs_failed": 0,
  "total_friction_count": 1,
  "verified_friction_count": 0
}

summary.md excerpt

The matching batch’s Markdown summary. Individual run and flow reports use report.md and flow.md.

- Status: completed
- Outcome: succeeded
- Runs attempted: 1
- Runs completed: 1
- Runs failed: 0
- Runs summarized: 1

Debug + Trace Files

Used when you need deeper diagnosis or reproducibility.

engineering_events.json + errors.jsonl for technical signal and runtime errors.
manifest.json for run metadata and artifact paths.
timeline.jsonl for event-by-event execution trace.

Need a command generated for your use case?

Share your URL, persona, and outcome goal. We can generate copy-pasteable commands for your workflow.

Request private beta access