Commands and Options
Command Reference¶
These are the commands that are available in Surfmeter Automator.
You can run them by typing them in the command line. For example, to register a client, you would run:
Here is the full list of commands:
| Command | Description |
|---|---|
register |
register the client |
startStudy |
start a study |
setPublicConfig |
set the public config |
getPublicConfig |
get the current public config and write it to a file |
reloadExtensionFromDisk |
reload the extension from disk |
checkRegistration |
check the registration state |
listStudyIds |
list the available study IDs in the public config |
launch |
launch Chrome |
updateExtension |
update Surfmeter extension |
updateConfig |
update config |
updateSelf |
update Surfmeter Automator |
loadSchedule |
load the cron schedule |
clearSchedule |
clear any cron schedule |
unregister |
unregister the client, deleting the profile and cache |
clearLockfile |
clear the Surfmeter lockfile and Chrome profile singleton locks (use with caution) |
flushDbToServer |
flush the local database to the server (send previously failed measurements) |
cleanupProfile |
cleanup the profile (remove all unnecessary files) |
setLabel |
set the label for the current client |
setTags |
set the tags for the current client |
Option Reference¶
The options are mostly self-explanatory and shown when you run --help.
General Options¶
These apply to all commands.
| Option | Type | Description |
|---|---|---|
--additionalExtensions |
array |
Path to additional extension directories (extracted) |
--autoOpenDevtools |
boolean |
Automatically open DevTools for all tabs (default: false) |
--chromeArgs |
array |
Additional Chrome command line arguments (feature flags will be merged with existing ones) |
--chromeBinary |
string |
Alternative path to the Chrome binary (defaults to the one found in $PATH; Chrome-based studies only) |
--chromeDriverBinary |
string |
Alternative path to the ChromeDriver binary (defaults to the one found in $PATH; Chrome-based studies only) |
--configDir |
string |
Path to the config directory containing the automatorConfig.json file |
--deeplinkLoadTimeout |
number |
Wait for how many seconds to detect Surfmeter Lab startup (default: 60) |
--deeplinkWaitTimeout |
number |
Wait for how many seconds to get deep link status (default: 60) |
--enableGpu |
boolean |
Enable GPU support for Chrome (default: false) |
--extensionDir |
string |
Path to the Surfmeter extension (extracted) |
--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) |
--headless |
boolean |
Use the built-in headless mode for all instances of Chrome (default: false) |
--keepNetworkRequests |
boolean |
Keep all logged network requests instead of deleting them after the study (default: false) |
--lockfileDir |
string |
Directory to use for lockfile |
--lockfileWaitTimeout |
number |
Wait for how many seconds to get lockfile status (default: 15) |
--logConsoleMessages |
boolean |
Log all console message via the Chrome DevTools Protocol to the console (default: false) |
--noAutoSetPublicConfig |
boolean |
Do not automatically set the public config (i.e., always use the public config in the extension) (default: false) |
--noClearCache |
boolean |
Do not clear caches when starting Chrome (default: false) |
--noClearCookies |
boolean |
Do not clear cookies when starting Chrome (preserves logins) (default: false) |
--noClearSystemDns |
boolean |
Do not clear the system DNS when starting (default: false) |
--noClose |
boolean |
Do not close the browser at the end of a run (default: false) |
--noDisableNetworkCache |
boolean |
Do not disable the network cache for individual requests (default: false) |
--noLoadSurfmeterLab |
boolean |
Do not load Surfmeter Lab extension (default: false) |
--noLogNetworkRequests |
boolean |
Do not log network requests via the Chrome DevTools Protocol. By default, all network requests are logged into a temporary file to enable additional statistics for content servers. (default: false) |
--profileDir |
string |
Path to the Chrome profile to use |
--publicConfigFile |
string |
Path to the Public Config JSON file (used by the getPublicConfig/setPublicConfig command and when starting a study) |
--sendNetworkPerformanceReports |
boolean |
Send network performance reports to the server. (default: false) |
--sendNetworkRequests |
boolean |
Send all network requests to the server. Note that this causes a lot of network traffic. (default: false) |
--userAgent |
string |
Override the user agent when starting the browser |
--windowSize |
string |
Set the window size in pixels (WxH), if unset will attempt to maximize window (Non-native studies only) |
startStudy Options¶
These options are specific to the startStudy command.
| Option | Type | Description |
|---|---|---|
--adHocPublicConfig |
string |
JSON-formatted public config to use for ad-hoc studies. When set, it will completely override the default public config. |
--downloadThroughput |
number |
Set download throughput for emulated network in kBit/s. Set to -1 to disable throttling. (Chrome-based studies only) (default: -1) |
--dynamicMetadata |
string |
Path to a file containing dynamic metadata (JSON5-formatted) to be merged with metadata |
--enableScreenRecording |
boolean |
Enable ffmpeg during study with ffmpeg libx264 (default: false) |
--enableTcpDump |
boolean |
Enable tcpdump during study (default: false) |
--extraHeaders |
string, or object |
Extra HTTP headers to send with each request. Can be a JSON object or a JSON-formatted string. |
--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 |
string |
Set preset for ffmpeg (slower is lower file size and higher CPU usage) (default: "medium") |
--filterStallingsThreshold |
number |
Threshold below which stallings will be filtered out in video measurements (in seconds) (default: 0) |
--flushDb |
boolean |
Flush the database before starting the study |
--flushDbTimeout |
number |
Timeout in seconds to wait for flushing the database (default: 10) |
--latency |
number |
Set latency for emulated network in milliseconds (Chrome-based studies only) (default: 0) |
--live |
boolean |
Run Measurement in Live mode, i.e. it will not stop at the pre-configured duration but continue forever or until the stream ends on its own (default: false) |
--metadata |
string, or object |
Metadata. Can be a JSON object or a JSON-formatted string. |
--muted |
boolean |
Mute browser audio (e.g. during video playback) (default: false) |
--noFakeMediaFiles |
boolean |
Do not tell Chrome to use the fake media files as input for testing web conferencing (default: false) |
--noFullscreen |
boolean |
Do not start the video studies in fullscreen mode |
--noGenerateFakeMediaFiles |
boolean |
Do not generate (or re-generate) the fake media files used for testing web conferencing (default: false) |
--notes |
string |
Notes |
--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) |
--screenRecordingDir |
string |
Save .mkv file to the specified directory (if not set, will be saved to a temporary directory) |
--screenRecordingTargetUrl |
string |
Target URL for screen recording (if set, will not write to a file) |
--sendTimeout |
number |
Maximum timeout for sending data in seconds. (default: 15) |
--sequential |
boolean |
Run studies sequentially instead of in parallel |
--startOffset |
number, or array |
Offset the start of the study in seconds. Pass multiple times to offset multiple studies by different amounts (default: 0) |
--studyId |
string, or array |
ID of the study (as in the public config). Pass multiple times to start multiple studies |
--studyTimeout |
number |
Maximum study timeout in seconds. This will be increased automatically depending on the individual study timeouts in the public config, if specified. (default: 300) |
--tcpDumpDir |
string |
Save .pcap file to the specified directory (if not set, will be saved to a temporary directory) |
--uploadThroughput |
number |
Set upload throughput for emulated network in kBit/s. Set to -1 to disable throttling. (Chrome-based studies only) (default: -1) |
--url |
string |
URL for ad-hoc study (cannot be used with studyId or adHocPublicConfig) |
--webRtcDumpDir |
string |
Save WebRTC dump file to the specified directory (if not set, will be saved to the cache directory) |
--webRtcDumpFile |
string |
Save WebRTC dump file to the specified file path (will override webRtcDumpDir if present) |
register Options¶
These options are specific to the register command.
| Option | Type | Description |
|---|---|---|
--label |
string |
Device label |
--registrationKey |
string |
Registration key (case-insensitive) |
--tags |
array |
Tags (comma-separated) |
loadSchedule Options¶
These options are specific to the loadSchedule command.
| Option | Type | Description |
|---|---|---|
--jobTypes |
array |
Type(s) of jobs to load (defaults to all) |
setLabel Options¶
These options are specific to the setLabel command.
| Option | Type | Description |
|---|---|---|
--label |
string |
Label |
setTags Options¶
These options are specific to the setTags command.
| Option | Type | Description |
|---|---|---|
--tags |
array |
Tags (comma-separated) |