Commands and Options
The command reference is generated from Automator's CLI definitions. Use surfmeter <command> --help to see the help for a command in your installed version.
Command Overview
surfmeter auth register: register this client with a Surfmeter serversurfmeter auth status: show the registration of this client and the installed version. Exit code 0: registered, 2: not registeredsurfmeter auth label show: print the label of this client. Exit code 2: not registeredsurfmeter auth label set: replace the label of this clientsurfmeter auth label clear: remove the label of this clientsurfmeter auth tags list: print the tags of this client, one per line. Exit code 2: not registeredsurfmeter auth tags set: replace the tags of this clientsurfmeter auth tags clear: remove all tags of this clientsurfmeter auth unregister: unregister this client on its server and remove its local identitysurfmeter auth migrate: copy the registration of an old Surfmeter Lab extension install into this clientsurfmeter browser install: install the browser Surfmeter uses (surfmeter browser install --withDeps)surfmeter browser installDeps: install only the OS packages the browser needs (normally as root)surfmeter browser list: list the browsers in the Playwright registrysurfmeter browser uninstall: remove the browsers Playwright installed for Surfmetersurfmeter browser launch: launch Chrome with the Surfmeter extension, as a study does, until it is closedsurfmeter cache clear: clear the Surfmeter cache (.cache.json), keeping registration, config and stored resultssurfmeter config show: print the measurement config, the schedule config, or both, as this automator uses themsurfmeter config set: replace a config file with a JSON or JSON5 file, or with stdin for "-"surfmeter config edit: edit a config file in $VISUAL or $EDITOR, and install it if it is validsurfmeter config update: download, validate and install the schedule and measurement configssurfmeter config migrate: copy the config files of an old install into the config directory and write the automator config as version 2surfmeter daemon start: run the scheduling daemon in the foreground (the default)surfmeter daemon status: show the jobs, schedule issues and runs of the running daemonsurfmeter daemon run: run a schedule entry nowsurfmeter daemon reload: re-read and validate the schedule configsurfmeter daemon ping: check that the daemon answers (exit code 2 if it does not)surfmeter daemon stop: print how to stop the daemon through its supervisorsurfmeter daemon install: install, enable and start the daemon as a systemd user service (Linux only)surfmeter daemon uninstall: stop and remove the systemd user service of the daemon (Linux only)surfmeter database flush: send stored results that have not reached the server yetsurfmeter database list: show the stored results (study chains) and whether they were sentsurfmeter profile cleanup: remove disposable data (BrowserMetrics, crash dumps, caches) from a persistent Chrome profile kept with --profileDirsurfmeter study list: list the study IDs in the measurement configsurfmeter study start: run one or more studiessurfmeter measure: measure a URL: a web page, a video, a speedtest or a network test (surfmeter measure speedtest://fast.com)surfmeter update: download and install a new version of Surfmeter (asks first when run in a terminal)
Options for All Commands
| Option | Type | Description |
|---|---|---|
--logMode | user, pretty, ldjson | Output mode: user (friendly terminal output, full log written to a file), pretty (readable log on stdout), ldjson (JSON lines on stdout). Default: user on a terminal, otherwise pretty in development and ldjson in production. |
--verbose | boolean | Show the full log on the terminal instead of the friendly output (same as --logMode pretty) |
--iWantToDangerouslyUseRoot | boolean | Allow running as root, which is not supported: all files written by the run belong to root, which breaks later runs as the measurement user. For a daemon running as root, set SURFMETER_OPTIONS__I_WANT_TO_DANGEROUSLY_USE_ROOT=1 instead, so its runs get it too. (default: False) |
Any option can also be set through an environment variable, which takes priority over all other sources. See Overriding Options via Environment Variables.
Command Reference
The arguments in angle brackets are required, and the arguments in square brackets are optional.
surfmeter auth register
Register this client with a Surfmeter server.
surfmeter auth register
| Option | Type | Description |
|---|---|---|
--configDir | string | Directory with automatorConfig.json, publicConfig.json and their .local.json overlays (default: config/ in the Surfmeter directory) |
--registrationKey, -r | string | Registration key (case-insensitive). Defaults to SURFMETER_DEFAULT_REGISTRATION_KEY, then to registrationKey in automatorConfig.json |
--server, -s | string | Surfmeter Server URL, or a shorthand name like "demo-analytics". Defaults to SURFMETER_DEFAULT_SERVER, which is how the Docker image supplies it |
--label, -l | string | Device label |
--tags, -t | string (repeatable) | Tags (repeatable, or comma-separated) |
surfmeter auth status
Show the registration of this client and the installed version. Exit code 0: registered, 2: not registered.
surfmeter auth status
| Option | Type | Description |
|---|---|---|
--json | boolean | Print the registration as one JSON object (default: False) |
--verify | boolean | Also authenticate against the Surfmeter server. Exit code 0: accepted, 1: the request failed, 2: not registered (default: False) |
surfmeter auth label show
Print the label of this client. Exit code 2: not registered.
surfmeter auth label show
| Option | Type | Description |
|---|---|---|
--json | boolean | Print the label as a JSON string, or null (default: False) |
surfmeter auth label set
Replace the label of this client.
surfmeter auth label set <label>
surfmeter auth label clear
Remove the label of this client.
surfmeter auth label clear
surfmeter auth tags list
Print the tags of this client, one per line. Exit code 2: not registered.
surfmeter auth tags list
| Option | Type | Description |
|---|---|---|
--json | boolean | Print the tags as a JSON array (default: False) |
surfmeter auth tags set
Replace the tags of this client.
surfmeter auth tags set <tags..>
surfmeter auth tags clear
Remove all tags of this client.
surfmeter auth tags clear
surfmeter auth unregister
Unregister this client on its server and remove its local identity.
surfmeter auth unregister
surfmeter auth migrate
Copy the registration of an old Surfmeter Lab extension install into this client.
surfmeter auth migrate
| Option | Type | Description |
|---|---|---|
--legacyInstallDir | string | Root of the old install: the directory with profile/, surfmeter-lab/ and the dist directory of the old automator |
--legacyProfileDir | string | Chrome profile of the old install, if it is not |
--legacyExtensionDir | string | Unpacked Surfmeter Lab extension of the old install, if it is not |
--server | string | Surfmeter Server URL or shorthand name, if it cannot be read from cache.json or the old extension |
--json | boolean | Print the result as one JSON object (default: False) |
--tsv | boolean | Print the result as tab-separated lines, for shell scripts (default: False) |
--chromeBinary | string | Path to the Chrome for Testing binary (defaults to the environment variable SURFMETER_CHROME_BINARY, or to the one managed by the Playwright registry; see surfmeter browser install) |
--globalTimeout | number | Wait for how many seconds before exiting Automator (default: 600) |
--globalTimeoutGracePeriod | number | Wait for how many seconds after the global timeout before forcefully exiting without sending a report (default: 10) |
surfmeter browser install
Install the browser Surfmeter uses (surfmeter browser install --withDeps).
surfmeter browser install [browser]
| Option | Type | Description |
|---|---|---|
--withDeps | boolean | Also install the OS packages Chrome needs. Runs as root/sudo, so not covered by --dryRun alone; see installDeps. (default: False) |
--force | boolean | Reinstall even if the browser is already present (default: False) |
--dryRun | boolean | Print what would happen (including download URLs) without changing anything (default: False) |
surfmeter browser installDeps
Install only the OS packages the browser needs (normally as root).
surfmeter browser installDeps [browser]
| Option | Type | Description |
|---|---|---|
--dryRun | boolean | Print what would happen (including download URLs) without changing anything (default: False) |
surfmeter browser list
List the browsers in the Playwright registry.
surfmeter browser list
| Option | Type | Description |
|---|---|---|
--json | boolean | Print the browsers as a JSON array (default: False) |
surfmeter browser uninstall
Remove the browsers Playwright installed for Surfmeter.
surfmeter browser uninstall
surfmeter browser launch
Launch Chrome with the Surfmeter extension, as a study does, until it is closed.
surfmeter browser launch [url]
| Option | Type | Description |
|---|---|---|
--profileDir | string | Path to a persistent Chrome profile to use and keep (by default, every browser gets a temporary profile that is removed afterwards) |
--chromeBinary | string | Path to the Chrome for Testing binary (defaults to the environment variable SURFMETER_CHROME_BINARY, or to the one managed by the Playwright registry; see surfmeter browser install) |
--additionalExtensions | string (repeatable) | Path to additional extension directories (extracted) |
--chromeArgs | string (repeatable) | Additional Chrome command line arguments (feature flags will be merged with existing ones). Do not specify the leading '--' for these args. |
--noLoadSurfmeterLab | boolean | Do not load Surfmeter Lab extension (default: False) |
--noClearCookies | boolean | Do not clear cookies when starting Chrome (preserves logins) (default: False) |
--noClearCache | boolean | Do not clear caches when starting Chrome (default: False) |
--noClearSystemDns | boolean | Do not clear the system DNS when starting (default: False) |
--noDisableNetworkCache | boolean | Do not disable the network cache for individual requests (default: False) |
--windowSize, -w | string | Set the window size in pixels (WxH), if unset will attempt to maximize window (Non-native studies only) |
--userAgent, -u | string | Override the user agent when starting the browser |
--noQuic | boolean | Do not let Chrome use QUIC/HTTP3. Chrome then uses TCP with HTTP/2 or HTTP/1.1 for every request, which is useful for comparing how a service behaves on either transport, or for networks where UDP is blocked or throttled. (default: False) |
--enableGpu | boolean | Enable GPU support for Chrome (default: False) |
--enableSandbox | boolean | Run Chrome with its sandbox instead of passing --no-sandbox. Works on a normal Linux install with unprivileged user namespaces, but not as root and not in the Docker image (no SYS_ADMIN capability). Chrome does not start when the sandbox is unavailable, so try it on one machine before enabling it everywhere. (default: False) |
--headless | boolean | Deprecated, maps to --display browser-headless for backward compatibility; use --display browser-headless directly instead (default: False) |
--display | string | How Chrome attaches to a display: 'auto' (reuse an existing X server or start one), 'xvfb' (always start a fresh virtual X server), 'browser-headless' (Chrome's built-in headless mode), or an X display spec like ':0' or ':123' (default: auto) |
--autoOpenDevtools | boolean | Automatically open DevTools for all tabs (default: False) |
--logConsoleMessages | boolean | Log the console messages of the page and of extension service workers, such as Surfmeter Lab, at info level instead of debug level (default: False) |
surfmeter cache clear
Clear the Surfmeter cache (.cache.json), keeping registration, config and stored results.
surfmeter cache clear
surfmeter config show
Print the measurement config, the schedule config, or both, as this automator uses them.
surfmeter config show [target]
| Option | Type | Description |
|---|---|---|
--configDir | string | Directory with automatorConfig.json, publicConfig.json and their .local.json overlays (default: config/ in the Surfmeter directory) |
--publicConfigFile, -p | string | Path to the public config (measurement config) file, relative to the config directory or absolute |
--paths | boolean | Print only the paths of the files, and whether the last good copy was used |
--json | boolean | Print one JSON object (default: False) |
--showSecrets | boolean | Do not mask password fields |
surfmeter config set
Replace a config file with a JSON or JSON5 file, or with stdin for "-".
surfmeter config set <target> <source>
| Option | Type | Description |
|---|---|---|
--configDir | string | Directory with automatorConfig.json, publicConfig.json and their .local.json overlays (default: config/ in the Surfmeter directory) |
--local | boolean | Write the .local.json overlay instead of the config file (default: False) |
--force | boolean | Write the file even though the next config update may overwrite it (default: False) |
surfmeter config edit
Edit a config file in $VISUAL or $EDITOR, and install it if it is valid.
surfmeter config edit <target>
| Option | Type | Description |
|---|---|---|
--configDir | string | Directory with automatorConfig.json, publicConfig.json and their .local.json overlays (default: config/ in the Surfmeter directory) |
--local | boolean | Write the .local.json overlay instead of the config file (default: False) |
--force | boolean | Write the file even though the next config update may overwrite it (default: False) |
surfmeter config update
Download, validate and install the schedule and measurement configs.
surfmeter config update
| Option | Type | Description |
|---|---|---|
--configDir | string | Directory with automatorConfig.json, publicConfig.json and their .local.json overlays (default: config/ in the Surfmeter directory) |
--verifyOnly | boolean | Download and validate the config without installing it. Exit code 0: a valid config is available, 2: the Surfmeter server has no config for this client, 1: the download failed or the config is invalid (default: False) |
surfmeter config migrate
Copy the config files of an old install into the config directory and write the automator config as version 2.
surfmeter config migrate
| Option | Type | Description |
|---|---|---|
--configDir | string | Directory with automatorConfig.json, publicConfig.json and their .local.json overlays (default: config/ in the Surfmeter directory) |
--legacyConfigDir | string | Config directory of the old install, e.g. ~/surfmeter/config |
--configSource | local, server | Where config updates come from afterwards: "server" (the Surfmeter server) or "local" (none, the files stay as they are). Default: server if the old config downloaded its config from a URL, local otherwise |
--overwrite | boolean | Replace files that already exist in the config directory (default: False) |
--relocateOutput | boolean | Point the log, recording and report settings of a version 1 config to the Surfmeter directory, and list the files to move there (default: False) |
--dryRun | boolean | Report what would be done without writing anything (default: False) |
--json | boolean | Print the summary as JSON on stdout (default: False) |
--tsv | boolean | Print the summary as tab-separated lines on stdout, for shell scripts (default: False) |
surfmeter daemon start
Run the scheduling daemon in the foreground (the default).
surfmeter daemon start
| Option | Type | Description |
|---|---|---|
--configDir | string | Directory with automatorConfig.json, publicConfig.json and their .local.json overlays (default: config/ in the Surfmeter directory) |
--socket | string | Path of the control socket (default: $SURFMETER_DAEMON_SOCKET or the runtime directory) |
--tickInterval | number | Scheduler tick interval in seconds, at most 1 (debugging only) |
surfmeter daemon status
Show the jobs, schedule issues and runs of the running daemon.
surfmeter daemon status
| Option | Type | Description |
|---|---|---|
--socket | string | Path of the control socket (default: $SURFMETER_DAEMON_SOCKET or the runtime directory) |
--json | boolean | Print the raw status as JSON (default: False) |
--tsv | boolean | Print the main fields and one line per job as tab-separated values, for shell scripts (default: False) |
surfmeter daemon run
Run a schedule entry now.
surfmeter daemon run <entryId>
| Option | Type | Description |
|---|---|---|
--socket | string | Path of the control socket (default: $SURFMETER_DAEMON_SOCKET or the runtime directory) |
--json | boolean | Print the raw response as JSON (default: False) |
--wait | boolean | Wait for the run to finish and report its outcome (default: False) |
surfmeter daemon reload
Re-read and validate the schedule config.
surfmeter daemon reload
| Option | Type | Description |
|---|---|---|
--socket | string | Path of the control socket (default: $SURFMETER_DAEMON_SOCKET or the runtime directory) |
--json | boolean | Print the raw response as JSON (default: False) |
surfmeter daemon ping
Check that the daemon answers (exit code 2 if it does not).
surfmeter daemon ping
| Option | Type | Description |
|---|---|---|
--socket | string | Path of the control socket (default: $SURFMETER_DAEMON_SOCKET or the runtime directory) |
surfmeter daemon stop
Print how to stop the daemon through its supervisor.
surfmeter daemon stop
surfmeter daemon install
Install, enable and start the daemon as a systemd user service (Linux only).
surfmeter daemon install
| Option | Type | Description |
|---|---|---|
--configDir | string | Directory with automatorConfig.json, publicConfig.json and their .local.json overlays (default: config/ in the Surfmeter directory) |
surfmeter daemon uninstall
Stop and remove the systemd user service of the daemon (Linux only).
surfmeter daemon uninstall
surfmeter database flush
Send stored results that have not reached the server yet.
surfmeter database flush
| Option | Type | Description |
|---|---|---|
--configDir | string | Directory with automatorConfig.json, publicConfig.json and their .local.json overlays (default: config/ in the Surfmeter directory) |
--sendTimeout | string | Maximum timeout for sending data in seconds. (default: 15) |
surfmeter database list
Show the stored results (study chains) and whether they were sent.
surfmeter database list
| Option | Type | Description |
|---|---|---|
--json | boolean | Print the study chains as a JSON array (default: False) |
--state | running, standalone, unsent, sent, rejected | Show only the study chains in this state |
surfmeter profile cleanup
Remove disposable data (BrowserMetrics, crash dumps, caches) from a persistent Chrome profile kept with --profileDir.
surfmeter profile cleanup
| Option | Type | Description |
|---|---|---|
--profileDir | string | Path to the persistent Chrome profile |
surfmeter study list
List the study IDs in the measurement config.
surfmeter study list
| Option | Type | Description |
|---|---|---|
--configDir | string | Directory with automatorConfig.json, publicConfig.json and their .local.json overlays (default: config/ in the Surfmeter directory) |
--publicConfigFile, -p | string | Path to the public config (measurement config) file, relative to the config directory or absolute |
--json | boolean | Print the IDs as a JSON array (default: False) |
surfmeter study start
Run one or more studies.
surfmeter study start
| Option | Type | Description |
|---|---|---|
--configDir | string | Directory with automatorConfig.json, publicConfig.json and their .local.json overlays (default: config/ in the Surfmeter directory) |
--publicConfigFile, -p | string | Path to the public config (measurement config) file, relative to the config directory or absolute |
--globalTimeout | number | Wait for how many seconds before exiting Automator (default: 600) |
--globalTimeoutGracePeriod | number | Wait for how many seconds after the global timeout before forcefully exiting without sending a report (default: 10) |
--profileDir | string | Path to a persistent Chrome profile to use and keep (by default, every browser gets a temporary profile that is removed afterwards) |
--chromeBinary | string | Path to the Chrome for Testing binary (defaults to the environment variable SURFMETER_CHROME_BINARY, or to the one managed by the Playwright registry; see surfmeter browser install) |
--additionalExtensions | string (repeatable) | Path to additional extension directories (extracted) |
--chromeArgs | string (repeatable) | Additional Chrome command line arguments (feature flags will be merged with existing ones). Do not specify the leading '--' for these args. |
--noLoadSurfmeterLab | boolean | Do not load Surfmeter Lab extension (default: False) |
--noClearCookies | boolean | Do not clear cookies when starting Chrome (preserves logins) (default: False) |
--noClearCache | boolean | Do not clear caches when starting Chrome (default: False) |
--noClearSystemDns | boolean | Do not clear the system DNS when starting (default: False) |
--noDisableNetworkCache | boolean | Do not disable the network cache for individual requests (default: False) |
--windowSize, -w | string | Set the window size in pixels (WxH), if unset will attempt to maximize window (Non-native studies only) |
--userAgent, -u | string | Override the user agent when starting the browser |
--noQuic | boolean | Do not let Chrome use QUIC/HTTP3. Chrome then uses TCP with HTTP/2 or HTTP/1.1 for every request, which is useful for comparing how a service behaves on either transport, or for networks where UDP is blocked or throttled. (default: False) |
--enableGpu | boolean | Enable GPU support for Chrome (default: False) |
--enableSandbox | boolean | Run Chrome with its sandbox instead of passing --no-sandbox. Works on a normal Linux install with unprivileged user namespaces, but not as root and not in the Docker image (no SYS_ADMIN capability). Chrome does not start when the sandbox is unavailable, so try it on one machine before enabling it everywhere. (default: False) |
--headless | boolean | Deprecated, maps to --display browser-headless for backward compatibility; use --display browser-headless directly instead (default: False) |
--display | string | How Chrome attaches to a display: 'auto' (reuse an existing X server or start one), 'xvfb' (always start a fresh virtual X server), 'browser-headless' (Chrome's built-in headless mode), or an X display spec like ':0' or ':123' (default: auto) |
--autoOpenDevtools | boolean | Automatically open DevTools for all tabs (default: False) |
--logConsoleMessages | boolean | Log the console messages of the page and of extension service workers, such as Surfmeter Lab, at info level instead of debug level (default: False) |
--noClose | boolean | Do not close the browser at the end of a run (default: False) |
--noLogNetworkRequests | boolean | Do not record the network requests of browser studies. Video measurements then have no response time and content server statistics, and web measurements no network performance reports. (default: False) |
--sendNetworkRequests | boolean | Send the recorded network requests of browser video measurements to the server. Note that this causes a lot of network traffic. (default: False) |
--sendNetworkPerformanceReports | boolean | Send a network performance report with each browser web measurement. (default: False) |
--sendByteCountReport | boolean | Send a byte count report to the server, with the bytes transferred per second and statistics on the throughput (browser video and web studies only). (default: False) |
--keepNetworkRequests | boolean | Keep the logged network requests in network-requests/ in the Surfmeter directory instead of deleting them after the study (default: False) |
--studyId, -s | string (repeatable) | ID of the study (as in the public config). Pass multiple times to start multiple studies |
--url | string (repeatable) | URL for an ad-hoc study, as for surfmeter measure (e.g. https://www.wikipedia.org, speedtest://fast.com, traceroute://8.8.8.8; see surfmeter measure --help for all). Cannot be used with studyId or adHocPublicConfig. Pass multiple times to start multiple studies |
--standalone | boolean | Run Measurement in standalone mode, i.e. it will not connect to the Measurement Server (default: False) |
--sendEventBundles | boolean | If set, collect and include event bundles in the request payload. If not set, skip adding events to bundles. (default: False) |
--notes, -n | string | Notes |
--metadata, -m | string | Metadata (JSON-formatted string) |
--dynamicMetadata | string | Path to a file containing dynamic metadata (JSON5-formatted) to be merged with metadata |
--extraHeaders | string | Extra HTTP headers to send with each request (JSON-formatted string) |
--muted, -q | boolean | Mute browser audio (e.g. during video playback) (default: False) |
--noFullscreen | boolean | Do not start the video studies in fullscreen mode |
--noFakeMediaFiles | boolean | Do not tell Chrome to use the fake media files as camera and microphone input for web conferencing (default: False) |
--noGenerateFakeMediaFiles | boolean | Do not generate (or re-generate) the fake media files used for web conferencing (default: False) |
--reportDir | string | Save the report as JSON to the specified directory |
--reportFile | string | Save the report as JSON to the specified file (will override reportDir if present) |
--sequential | boolean | Run studies sequentially instead of in parallel |
--startOffset | number (repeatable) | Offset the start of the study in seconds. Pass multiple times to offset multiple studies by different amounts (default: 0) |
--studyTimeout, -t | string | Maximum run time of one study in seconds. A study still running then is aborted with the reason studyTimeout; native tools are stopped. (default: 300) |
--sendTimeout | string | Maximum timeout for sending data in seconds. (default: 15) |
--keepMeasurementData | boolean | Keep the study chain file under data/ after the server accepted it. By default it is deleted after a successful send; a failed send always keeps it. (default: False) |
--latency | number | Set latency for emulated network in milliseconds (Chrome-based studies only) (default: 0) |
--uploadThroughput | number | Set upload throughput for emulated network in kBit/s. Set to -1 to disable throttling. (Chrome-based studies only) (default: -1) |
--downloadThroughput | number | Set download throughput for emulated network in kBit/s. Set to -1 to disable throttling. (Chrome-based studies only) (default: -1) |
--enableTcpDump | boolean | Capture the network traffic of the run with tcpdump (needs capture permission, no root) (default: False) |
--tcpDumpDir | string | Save the .pcap file to this directory (if not set, saved to pcaps/ in the Surfmeter directory) |
--enableHarFile | boolean | Record the HTTP traffic of each browser study into a HAR file (without response bodies) (default: False) |
--harFileDir | string | Save the .har files to this directory (if not set, saved to har-files/ in the Surfmeter directory) |
--enableScreenRecording | boolean | Record the screen during the run with ffmpeg and libx264 (default: False) |
--screenRecordingDir | string | Save the .mp4 file to this directory (if not set, saved to recordings/ in the Surfmeter directory) |
--screenRecordingTargetUrl | string | Target URL for screen recording (if set, will not write to a file) |
--ffmpegCrf | number | Set CRF for ffmpeg (lower is better quality, higher is better compression) (default: 23) |
--ffmpegFps | number | Set FPS for ffmpeg (will be inferred from display refresh rate if not set) |
--ffmpegPreset | ultrafast, superfast, veryfast, faster, fast, medium, slow, slower, veryslow | Set preset for ffmpeg (slower is lower file size and higher CPU usage) (default: veryfast) |
--flushDb | boolean | After the study, send results of earlier runs that have not reached the server yet |
--flushDbTimeout | number | Timeout in seconds for sending earlier results after the study (--flushDb) (default: 10) |
--adHocPublicConfig | string | JSON-formatted public config to use for ad-hoc studies. When set, it will completely override the default public config. |
--filterStallingsThreshold | number | Threshold below which stallings will be filtered out in video measurements (in seconds) (default: 0) |
surfmeter measure
Measure a URL: a web page, a video, a speedtest or a network test (surfmeter measure speedtest://fast.com).
surfmeter measure <url>
| Option | Type | Description |
|---|---|---|
--configDir | string | Directory with automatorConfig.json, publicConfig.json and their .local.json overlays (default: config/ in the Surfmeter directory) |
--globalTimeout | number | Wait for how many seconds before exiting Automator (default: 600) |
--globalTimeoutGracePeriod | number | Wait for how many seconds after the global timeout before forcefully exiting without sending a report (default: 10) |
--profileDir | string | Path to a persistent Chrome profile to use and keep (by default, every browser gets a temporary profile that is removed afterwards) |
--chromeBinary | string | Path to the Chrome for Testing binary (defaults to the environment variable SURFMETER_CHROME_BINARY, or to the one managed by the Playwright registry; see surfmeter browser install) |
--additionalExtensions | string (repeatable) | Path to additional extension directories (extracted) |
--chromeArgs | string (repeatable) | Additional Chrome command line arguments (feature flags will be merged with existing ones). Do not specify the leading '--' for these args. |
--noLoadSurfmeterLab | boolean | Do not load Surfmeter Lab extension (default: False) |
--noClearCookies | boolean | Do not clear cookies when starting Chrome (preserves logins) (default: False) |
--noClearCache | boolean | Do not clear caches when starting Chrome (default: False) |
--noClearSystemDns | boolean | Do not clear the system DNS when starting (default: False) |
--noDisableNetworkCache | boolean | Do not disable the network cache for individual requests (default: False) |
--windowSize, -w | string | Set the window size in pixels (WxH), if unset will attempt to maximize window (Non-native studies only) |
--userAgent, -u | string | Override the user agent when starting the browser |
--noQuic | boolean | Do not let Chrome use QUIC/HTTP3. Chrome then uses TCP with HTTP/2 or HTTP/1.1 for every request, which is useful for comparing how a service behaves on either transport, or for networks where UDP is blocked or throttled. (default: False) |
--enableGpu | boolean | Enable GPU support for Chrome (default: False) |
--enableSandbox | boolean | Run Chrome with its sandbox instead of passing --no-sandbox. Works on a normal Linux install with unprivileged user namespaces, but not as root and not in the Docker image (no SYS_ADMIN capability). Chrome does not start when the sandbox is unavailable, so try it on one machine before enabling it everywhere. (default: False) |
--headless | boolean | Deprecated, maps to --display browser-headless for backward compatibility; use --display browser-headless directly instead (default: False) |
--display | string | How Chrome attaches to a display: 'auto' (reuse an existing X server or start one), 'xvfb' (always start a fresh virtual X server), 'browser-headless' (Chrome's built-in headless mode), or an X display spec like ':0' or ':123' (default: auto) |
--autoOpenDevtools | boolean | Automatically open DevTools for all tabs (default: False) |
--logConsoleMessages | boolean | Log the console messages of the page and of extension service workers, such as Surfmeter Lab, at info level instead of debug level (default: False) |
--noClose | boolean | Do not close the browser at the end of a run (default: False) |
--noLogNetworkRequests | boolean | Do not record the network requests of browser studies. Video measurements then have no response time and content server statistics, and web measurements no network performance reports. (default: False) |
--sendNetworkRequests | boolean | Send the recorded network requests of browser video measurements to the server. Note that this causes a lot of network traffic. (default: False) |
--sendNetworkPerformanceReports | boolean | Send a network performance report with each browser web measurement. (default: False) |
--sendByteCountReport | boolean | Send a byte count report to the server, with the bytes transferred per second and statistics on the throughput (browser video and web studies only). (default: False) |
--keepNetworkRequests | boolean | Keep the logged network requests in network-requests/ in the Surfmeter directory instead of deleting them after the study (default: False) |
--standalone | boolean | Run Measurement in standalone mode, i.e. it will not connect to the Measurement Server (default: False) |
--sendEventBundles | boolean | If set, collect and include event bundles in the request payload. If not set, skip adding events to bundles. (default: False) |
--notes, -n | string | Notes |
--metadata, -m | string | Metadata (JSON-formatted string) |
--dynamicMetadata | string | Path to a file containing dynamic metadata (JSON5-formatted) to be merged with metadata |
--extraHeaders | string | Extra HTTP headers to send with each request (JSON-formatted string) |
--muted, -q | boolean | Mute browser audio (e.g. during video playback) (default: False) |
--noFullscreen | boolean | Do not start the video studies in fullscreen mode |
--reportDir | string | Save the report as JSON to the specified directory |
--reportFile | string | Save the report as JSON to the specified file (will override reportDir if present) |
--studyTimeout, -t | string | Maximum run time of one study in seconds. A study still running then is aborted with the reason studyTimeout; native tools are stopped. (default: 300) |
--sendTimeout | string | Maximum timeout for sending data in seconds. (default: 15) |
--keepMeasurementData | boolean | Keep the study chain file under data/ after the server accepted it. By default it is deleted after a successful send; a failed send always keeps it. (default: False) |
--latency | number | Set latency for emulated network in milliseconds (Chrome-based studies only) (default: 0) |
--uploadThroughput | number | Set upload throughput for emulated network in kBit/s. Set to -1 to disable throttling. (Chrome-based studies only) (default: -1) |
--downloadThroughput | number | Set download throughput for emulated network in kBit/s. Set to -1 to disable throttling. (Chrome-based studies only) (default: -1) |
--enableTcpDump | boolean | Capture the network traffic of the run with tcpdump (needs capture permission, no root) (default: False) |
--tcpDumpDir | string | Save the .pcap file to this directory (if not set, saved to pcaps/ in the Surfmeter directory) |
--enableHarFile | boolean | Record the HTTP traffic of each browser study into a HAR file (without response bodies) (default: False) |
--harFileDir | string | Save the .har files to this directory (if not set, saved to har-files/ in the Surfmeter directory) |
--enableScreenRecording | boolean | Record the screen during the run with ffmpeg and libx264 (default: False) |
--screenRecordingDir | string | Save the .mp4 file to this directory (if not set, saved to recordings/ in the Surfmeter directory) |
--screenRecordingTargetUrl | string | Target URL for screen recording (if set, will not write to a file) |
--ffmpegCrf | number | Set CRF for ffmpeg (lower is better quality, higher is better compression) (default: 23) |
--ffmpegFps | number | Set FPS for ffmpeg (will be inferred from display refresh rate if not set) |
--ffmpegPreset | ultrafast, superfast, veryfast, faster, fast, medium, slow, slower, veryslow | Set preset for ffmpeg (slower is lower file size and higher CPU usage) (default: veryfast) |
--filterStallingsThreshold | number | Threshold below which stallings will be filtered out in video measurements (in seconds) (default: 0) |
surfmeter update
Download and install a new version of Surfmeter (asks first when run in a terminal).
surfmeter update
| Option | Type | Description |
|---|---|---|
--configDir | string | Directory with automatorConfig.json, publicConfig.json and their .local.json overlays (default: config/ in the Surfmeter directory) |
--check | boolean | Show which version is available, without installing it. Exit code 0: no newer version, 2: a newer version is available, 1: the check failed (default: False) |
--yes, -y | boolean | Install a newer version without asking, also in a terminal (default: False) |
Old Command Names
The command names of Automator 1.x still work, but print a warning. Use the new ones instead:
register:surfmeter auth registercheckRegistration:surfmeter auth statussetLabel:surfmeter auth label setsetTags:surfmeter auth tags setunregister:surfmeter auth unregistermigrateBrowserExtension:surfmeter auth migratestartStudy:surfmeter study startlistStudyIds:surfmeter study listupdateConfig:surfmeter config updateupdateSelf:surfmeter updateflushDbToServer:surfmeter database flushcleanupProfile:surfmeter profile cleanupclearCache:surfmeter cache clearmigrateConfig:surfmeter config migrate
The commands loadSchedule and clearSchedule print what to use instead, and exit with an error. See Migrating from Automator 1.x.