Commands and Options
Command Reference¶
| Command | Description |
|---|---|
register |
Registers the client with the Surfmeter service. This is required before you can start a study. For details see Registration. |
startStudy |
Starts a new study. For details see Running Studies. |
setPublicConfig |
Sets the public config from a file. This is usually not needed. For details see Changing the Configuration. |
getPublicConfig |
Gets the current public config and writes it to a file. For details see Changing the Configuration. |
reloadExtensionFromDisk |
Reloads the Surfmeter extension from disk. |
checkRegistration |
Checks the registration state of the client. For registering, see Registration. |
listStudyIds |
Lists the available study IDs in the public config. |
launch |
Launches the Chrome browser for debugging purposes. |
updateExtension |
Updates the Surfmeter extension. For details see Updating. |
updateConfig |
Updates the config. For details see Updating. |
updateSelf |
Updates the Surfmeter Automator. For details see Updating. |
loadSchedule |
Loads the cron schedule. For details see Scheduling Studies. |
clearSchedule |
Clears any cron schedule. For details see Scheduling Studies. |
unregister |
Unregisters the client, deleting the profile and cache. For details see Registration. |
clearLockfile |
Clears the Surfmeter lockfile and Chrome profile singleton locks (use with caution). |
flushDbToServer |
Flushes the local database to the server (sends previously failed measurements). |
cleanupProfile |
Cleans up the Chrome profile by removing obsolete browser metrics files. |
setLabel |
Sets the label for the current client. |
setTags |
Sets 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 |
|---|---|---|
--profileDir |
string | Path to the Chrome profile to use (default: ../profile) |
--configDir |
string | Path to the config directory containing the automatorConfig.json file (default: ../config) |
--extensionDir |
string | Path to the Surfmeter extension (extracted) (default: ../surfmeter-lab/extension/chrome) |
--publicConfigFile |
string | Path to the Public Config JSON file (used by the getPublicConfig/setPublicConfig command and when starting a study) (default: ../config/publicConfig.json) |
--noAutoSetPublicConfig |
boolean | Do not automatically set the public config (i.e., always use the public config in the extension) (default: false) |
--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) |
--additionalExtensions |
array | Path to additional extension directories (extracted) |
--noLoadSurfmeterLab |
boolean | Do not load the Surfmeter Lab extension (default: false) |
--noClose |
boolean | Do not close the browser at the end of a run (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) |
--logConsoleMessages |
boolean | Log all console message via the Chrome DevTools Protocol to the console (default: false) |
--logNetworkRequests |
boolean | Log all network requests via the Chrome DevTools Protocol into a temporary file (default: false) |
--sendNetworkRequests |
boolean | Send all network requests to the server. Requires --logNetworkRequests. Note that this causes a lot of network traffic. (default: false) |
--keepNetworkRequests |
boolean | Keep all logged network requests instead of deleting them after the study (default: false) |
--sendNetworkPerformanceReports |
boolean | Send network performance reports to the server. Requires --logNetworkRequests. (default: false) |
--deeplinkLoadTimeout |
number | Wait for how many seconds to detect Surfmeter Lab startup (default: 15) |
--deeplinkWaitTimeout |
number | Wait for how many seconds to get deep link status (default: 15) |
--lockfileWaitTimeout |
number | Wait for how many seconds to get lockfile status (default: 15) |
--globalTimeout |
number | Wait for how many seconds before exiting Automator (default: 600) |
--globalTimeoutGracePeriod |
number | Wait for how many seconds before hard-exiting Automator after the global timeout (default: 10) |
--lockfileDir |
string | Directory to use for lockfile (default: A temporary directory) |
--windowSize |
string | Set the window size in pixels (WxH), if unset will attempt to maximize window (Non-native studies only) |
--userAgent |
string | Override the user agent when starting the browser |
--enableGpu |
boolean | Enable GPU support for Chrome (default: false) |
--headless |
boolean | Use the built-in headless mode for all instances of Chrome (default: false) |
--help |
boolean | Show help |
--version |
boolean | Show version number |
startStudy Options¶
These options are specific to the startStudy command.
| Option | Type | Description |
|---|---|---|
--studyId |
array | ID of the study (as in the public config). Pass multiple times to start multiple studies (required) |
--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) |
--notes |
string | Notes |
--metadata |
string | Metadata (JSON-formatted string) |
--muted |
boolean | Mute browser audio (e.g. during video playback) |
--noFullscreen |
boolean | Do not start the video studies in fullscreen mode |
--noFakeMediaFiles |
boolean | Do not generate fake media files for conferencing studies (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 | Offset the start of the study in seconds. Pass multiple times to offset multiple studies by different amounts (default: 0) |
--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) |
--sendTimeout |
number | Maximum timeout for sending data in seconds. (default: 15) |
--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 | Enable tcpdump during study (default: false) |
--tcpDumpDir |
string | Save .pcap file to the specified directory (if not set, will be saved to a temporary directory) |
--enableScreenRecording |
boolean | Enable ffmpeg during study with ffmpeg libx264 (default: false) |
--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) |
--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) (choices: "ultrafast", "superfast", "veryfast", "faster", "fast", "medium", "slow", "slower", "veryslow") (default: medium) |
--flushDb |
boolean | Flush the database before starting the study (default: false) |
--flushDbTimeout |
number | Timeout in seconds to wait for flushing the database (default: 10) |
register Options¶
These options are specific to the register command.
| Option | Type | Description |
|---|---|---|
--registrationKey |
string | Registration key (required) |
--label |
string | Device label |
--tags |
array | Tags |
loadSchedule Options¶
These options are specific to the loadSchedule command.
| Option | Type | Description |
|---|---|---|
--jobTypes |
array | Type(s) of jobs to load (choices: "study", "updateExtension", "updateConfig", "updateSelf") (defaults to all) |
setLabel Options¶
These options are specific to the setLabel command.
| Option | Type | Description |
|---|---|---|
--label |
string | Label for the client |
setTags Options¶
These options are specific to the setTags command.
| Option | Type | Description |
|---|---|---|
--tags |
array | Tags for the client (comma-separated list) |