Command reference#

Every subcommand, and the flags that matter. surge help prints the short form; this is the long one.

Exit codes: 0 pass · 1 a breached threshold or a real regression · 2 a setup error, reported before any traffic is sent. A CI job needs no output parsing.

Before the load, in order#

Each of these answers something the one before it cannot.

surge validate  perf/checkout.yaml   # the file
surge preflight perf/checkout.yaml   # the world
surge verify    perf/checkout.yaml   # the scenario

validate sends nothing — no request, no connection. Run it after every edit, including when the target is not up. It prints the kind of test, what the run will be judged on, and every step as the engine will see it, so a WebSocket step reads as ws send+receive on live rather than as a line of YAML you hope is right.

preflight costs one request per target, monitor and agent, and ends in GO or NO-GO. It answers what nobody writes down: does the name resolve, is the certificate about to expire, is the "staging" URL actually this laptop, are there enough rows in the CSV for the peak, is the monitor endpoint serving a dashboard instead of metrics, do the agents agree on the time, does this machine have the file descriptors for the plan.

verify runs one iteration of every role against the real system and prints every step, every extract and every check — WebSocket steps included, one line per message with the repeat numbered. The failure it catches: an extract that stopped matching, so every later step sends the literal ${token} and five thousand users spend two hours getting 401s you read as the system being broken.

surge run#

Load

• -vus N closed model · -rate R open model · -duration D
• -iterations N run exactly N and stop
• -warmup D a leading period excluded from the final stats
• -base-url URL point the same scenario at another environment
• -var k=v set or override a scenario variable (repeatable)
• -tags a,b / -exclude-tags c run a subset; exclusion wins

Before the load

• -verify rehearse one pass of every role first, and refuse to apply load if it fails. Cheap. Use it on anything long or large.

Reports

• -html F -json F -csv F -failures F -snapshot F
• -prometheus F -influx F -webhook URL
• -log-requests F one line per request, for outlier forensics
• -percentiles 50,95,99.9 beyond the default four

Diagnosis

• -timings where each request's time went, with the dominant phase named
• -monitor URL (or name=url, repeatable) scrape the target's own metrics and rank what moved with the latency
• -monitor-interval D
• -analyze knee detection, bottleneck, trustworthiness
• -web :8088 the live dashboard, thresholds evaluated every second

Safety

• -abort-on "error_rate > 50% for 15s" stop a test that has already failed, before it takes the environment with it

Across machines

• -shard N/M this machine's part of a split run — the load and the feeder rows divided from the shard number alone, no coordinator
• -agents a:7777,b:7777 coordinator mode, raw histograms merged
• -snapshot F the mergeable form; combine with surge merge

surge quick#

A run with no file: surge builds the scenario in memory from the flags.

surge quick https://api.example.com/health \
  -vus 50 -duration 30s -threshold "p95 < 200ms"

It takes the run flags that make sense without a scenario. Good for "is this endpoint alive under any load at all"; past that, write a file, because a journey is not one URL.

surge discover#

surge discover perf/checkout.yaml -slo "p95 < 500ms, error_rate < 1%" -max-rate 5000

An SLO expression can name a request or a group: action, not only the totals. Finding capacity has the rest.

surge web#

surge web -dir perf            # http://127.0.0.1:8099
surge web -dir perf -open      # and open a browser

See the live dashboard and the control UI.

surge agent#

surge agent -listen 0.0.0.0:7777 -token "$SURGE_TOKEN"

Serves one run at a time to a coordinator. A second run while one is going is refused rather than queued.

An agent runs whatever scenario it is sent, so both refusals are deliberate: see the security contract.