PRIVATE BETA SURFACE

Flock Synthetic CLI

Run synthetic users from your terminal and generate evidence-backed findings your team can address with confidence.

Use this reference in three steps: choose a run type, define shared context flags, then execute commands and review the output artifacts.

Evidence-Backed by Default

Flock findings must tie to observable artifacts: UI text, element states, screenshots, network failures, console/runtime errors, or deterministic trace events. We optimize for low hallucination and addressable fixes.

Quickstart Recipes

Choose the run mode first, then copy a starter command and replace placeholders with your own URL and persona details.

Single run

Use for one persona and one primary journey when you want fast validation of a specific flow.

Flow run

Use when navigation paths are unclear and you want step-by-step exploration or replay evidence.

Batch comparison

Use to compare outcomes across multiple personas on the same target and quantify divergence.

Copy/paste starter commands:

Single run

node synthetic/run.js \
  --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

node synthetic/flow-run.js \
  --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

node synthetic/batch-run.js \
  --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 run, flow-run, and batch-run.

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

Control whether evidence is captured live, replayed, or hybrid.

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

Command Reference

Copy these commands into your terminal and replace placeholder values like <https://...> and <persona-id>.

Single persona run

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

node synthetic/run.js --url <https://...> --persona <persona-id>

Flow run (multi-step)

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

node synthetic/flow-run.js --url <https://...> --persona <persona-id> --flow-mode roam

Batch run (persona comparison)

Compare outcomes across personas, or generate a population sample.

node synthetic/batch-run.js --url <https://...> --personas <p1,p2,p3>

Render existing artifacts

Render shareable markdown reports from existing run and flow artifacts.

node synthetic/render.js --run <runs/run_example>
node synthetic/render-flow.js --run <runs/run_example>

Key Output Files

Start with these day-to-day files. They carry the evidence payloads and traces behind each claim.

output.json / flow.json

Primary findings for a run or multi-step flow, including frictions, opportunities, and agent reasoning.

{
  "schema_version": "2.0.0",
  "persona_id": "novice-user",
  "overall_impression": {
    "clarity": 0.6,
    "trust": 0.8,
    "would_recommend": 0.7,
    "frustration_level": 3,
    "abandonment_risk": "low"
  },
  "step_reasoning": "I was trying to figure out what this site offers and how I could try it out...",
  "friction_events": [
    {
      "event_id": "friction-01",
      "severity": 1,
      "emotion": "confused",
      "summary": "Header button has no clear label or symbol.",
      "suggested_fix": "Add a clear label or recognizable icon.",
      "evidence": {
        "screenshot": "artifacts://runs/run_013/step-03.png",
        "dom_excerpt": "<button aria-label=''></button>",
        "trace_event": "timeline://run_013/events/091"
      }
    }
  ],
  "opportunities": [
    {
      "summary": "Clarify shipping method labels with delivery-time helper text.",
      "rationale": "Reduce selection errors for novice personas at checkout.",
      "confidence": 0.8
    }
  ]
}

summary.json / summary.md

Batch-level aggregation across personas, including totals and top issue patterns.

{
  "batch_id": "batch_20260223_040136_c9a3",
  "status": "completed",
  "runs_attempted": 3,
  "runs_completed": 3,
  "runs_failed": 0,
  "personas": [
    {
      "persona_id": "novice-user",
      "friction_count": 4,
      "engineering_issue_count": 1
    }
  ]
}

report.md / flow.md

Shareable markdown summaries for stakeholders and async reviews.

## Summary
Summary: Signup path is understandable, but trust signals are weak above the fold.

## Friction Events
- (sev 1) Header button has no clear label.
  - Suggested fix: Add label or recognizable icon.
  - Confidence: 0.82
  - Evidence: [home-header]

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.

Get Started