Sauce Connect Proxy 4 CLI Reference

Below is a list of flags to use on your Sauce Connect Proxy v4.x.x command line to specify parameters. Supported versions are indicated in the headers.

note

This is Sauce Connect Version 4 CLI documentation. The Sauce Connect Proxy version 5 major release introduced breaking CLI changes. Please refer to Sauce Connect Proxy 5 CLI Reference for details.

What You'll Need

Make sure you're using the latest Sauce Connect Proxy version. Otherwise, some flags may not work.
See Sauce Connect Quickstart and Basic Setup for Sauce Connect Proxy for setup instructions and use cases.

tip

You can view the entire list of CLI options by running the --help flag.

Main

`--user`

| REQUIRED | STRING | 4.8.x 4.9.x |

Description: Sets your Sauce Labs username. For additional security, you can set this as an environment variable.
Environment variable: SAUCE_USERNAME or SAUCE_USER
Shorthand: -u

`--api-key`

| REQUIRED | STRING | 4.8.x 4.9.x |

Description: Sets your Sauce Labs API key. This will be the same as your Access Key. For additional security, you can set this as an environment variable.
Environment variable: SAUCE_ACCESS_KEY or SAUCE_API_KEY
Shorthand: -k

`--config-file`

| OPTIONAL | STRING | 4.8.x 4.9.x |

Description: Defines the local path to a YAML file containing a Sauce Connect Proxy configuration. For instructions, Configuring Tunnels with a YAML File.
Environment variable: SAUCE_CONFIG_FILE
Shorthand: -c

caution

--config-file is required if you're using a YAML file to configure Sauce Connect Proxy.

`--region`

| OPTIONAL | STRING | 4.8.x 4.9.x |

Description: Sets your Sauce Labs data center endpoint (for example, us-west or eu-central). Default: If you don't specify a data center, the default value is us-west.
Environment variable: SAUCE_REGION
Shorthand: -r

`--rest-url`

| OPTIONAL | STRING | 4.8.x 4.9.x |

Description: Sets the URL for the data center endpoint of the location where the device you're testing on is hosted.
Environment variable: SAUCE_REST_URL
Shorthand: -x

#US-West-1 ("-r us-west" can be used instead)
-x https://api.us-west-1.saucelabs.com/rest/v1

#EU-Central-1 ("-r eu-central" can be used instead)
-x https://api.eu-central-1.saucelabs.com/rest/v1

`--shared-tunnel`

| OPTIONAL | 4.8.x 4.9.x |

Description: Changes tunnel sharing permissions so that all users in an organization can use Sauce Connect Proxy tunnels, rather than just the tunnel owner (admin). For more information, see Sharing Sauce Connect Proxy Tunnels.
Environment variable: SAUCE_SHARED_TUNNEL
Shorthand: -s

`--tunnel-identifier`

| OPTIONAL | STRING | 4.8.x |

Description: Assigns a name to a Sauce Connect Proxy tunnel. It can also assign a name to a group of tunnels in the same High Availability pool, when used with --tunnel-pool. Must be in ASCII format.

You can run tests using this tunnel by specifying the tunnelName in your test capabilities. To learn about the syntax for setting this as a capability, see Test Configuration Options.
Environment variable: SAUCE_TUNNEL_IDENTIFIER
Shorthand: -i

Tunnel Identifier = Tunnel Name

This value populates the Tunnel Name field on the Sauce Labs Tunnels page, not the Tunnel ID (which is an auto-generated tunnel UUID). You can use the --tunnel-identifier or --tunnel-name flags interchangeably.

caution

This flag is deprecated and will be removed in future versions. It is replaced by --tunnel-name.

`--tunnel-name`

| OPTIONAL | STRING | 4.8.x 4.9.x |

`--tunnel-pool`

| OPTIONAL | STRING | 4.8.x 4.9.x |

Description: Launches a high availability tunnel pool along with the --tunnel-name flag. For more info, see High Availability Setup.
Environment variable: n/a
Shorthand: n/a

Tunnel Configuration

`--direct-domains`

| OPTIONAL | STRING | 4.8.x 4.9.x |

Description: Sets domain(s) that are requested through the public internet instead of the Sauce Connect Proxy tunnel. This is the inverse of --tunnel-domains. When adding multiple domains, format as a comma-separated list. See Tuning Sauce Connect Proxy Traffic for more information.
Environment variable: SAUCE_DIRECT_DOMAINS
Shorthand: -D

`--no-ssl-bump-domains`

| OPTIONAL | STRING | 4.8.x 4.9.x |

Description: Sets domain(s) that do not require SSL resigning. Requests that include hosts matching one of these domains will not be SSL re-encrypted. When adding multiple domains, format as a comma-separated list. See SSL Certificate Bumping for more information about scenarios in which might want to use this command.
Environment variable: SAUCE_NO_SSL_BUMP_DOMAINS
Shorthand: -B

`--fast-fail-regexps`

| OPTIONAL | STRING | 4.8.x 4.9.x |

Description: Allows you to set a deny-list of URL patterns. Requests with URLs matching one of these will get dropped instantly and will not go through the tunnel. Tests for app and site degradation based on missing assets or resources. Can be used to simulate non-loading of scripts, styles, or other resources. Use this option followed by a comma-separated list of regular expressions. See the Sauce Connect Proxy FAQ for an example.
Environment variable: SAUCE_FAST_FAIL_REGEXPS
Shorthand: -F

`--tunnel-domains`

| OPTIONAL | STRING | 4.8.x 4.9.x |

Description: Sets domain(s) that are requested through the Sauce Connect Proxy tunnel. This is the inverse of --direct-domains. When adding multiple domains, format them as a comma-separated list. See Tuning Sauce Connect Proxy Traffic for more information.
Environment variable: SAUCE_TUNNEL_DOMAINS
Shorthand: -t

`--extra-info`

| OPTIONAL | STRING | 4.8.x 4.9.x |

Description: JSON string that contains an advanced tunnel configuration.

Option	Description	Example
`inject-forwarded-for`	Do not remove X-FORWARDED-FOR header from the proxied HTTP requests.	`--extra-info '{"inject-forwarded-for": true}'`
`reply_body_max_size`	Set limit to the reply body size (the default is 500 MB).	`--extra-info '{"reply_body_max_size": "30 MB"}'`

You can specify a combination of several options. For example:

--extra-info '{"inject-forwarded-for": true, "reply_body_max_size": "300 MB"}'

Environment variable: SAUCE_EXTRA_INFO
Shorthand: n/a

External Proxy Configuration

`--autodetect`

| OPTIONAL | BOOLEAN | 4.8.x 4.9.x |

Description: Enables the auto-detection of system proxy settings. Inverse of --no-autodetect. Default: true. See also Automatic Proxy Auto-Configuration.
Environment variable: SAUCE_AUTODETECT
Shorthand: n/a

`--no-autodetect`

| OPTIONAL | BOOLEAN | 4.8.x 4.9.x |

Description: Disables the auto-detection of system proxy settings. See Automatic Proxy Auto-Configuration for more information.
Environment variable: SAUCE_NO_AUTODETECT
Shorthand: n/a

`--pac`

| OPTIONAL | STRING | 4.8.x 4.9.x |

Description: Defines external proxy auto-configuration (PAC) URI. You can input http(s) or local file://URL. Absolute paths are required when specifying a local PAC file. --pac supports the standard file URL format (that is, file://auth-path/local-path). On Windows, the format looks like file:///C:/path/to/file. For more information, see Sauce Connect Proxy Setup with Additional Proxies.
Environment variable: SAUCE_PAC
Shorthand: n/a

Mac or Linux
Windows

--pac file://Users/JohnSmith/Desktop/MyPac.pac

--pac file:///C:/Users/JohnSmith/Desktop/MyPac.pac

`--pac-auth`

| OPTIONAL | STRING | 4.8.x 4.9.x |

Description: Supplies PAC authentication in the format username:password@host:port. This option can be used multiple times for each authenticated host in the PAC file.
Environment variable: SAUCE_PAC_AUTH
Shorthand: n/a

note

Use a comma separated list when using multiple PAC settings via environment variable. Do not include spaces in this list. For example: SAUCE_PAC_AUTH=username:password@host:port,username2:password@host2:port

`--proxy`

| OPTIONAL | STRING | 4.8.x 4.9.x |

Description: Defines external proxy host:port where you want to route Sauce Labs test traffic. For example, the traffic from a Firefox desktop test.
Environment variable: SAUCE_PROXY
Shorthand: -p

`--proxy-localhost`

| OPTIONAL | BOOLEAN | 4.8.x 4.9.x |

Description: Setting this to true supports sending requests to localhost through the upstream proxy. This includes scenarios where an upstream proxy is hosted on localhost. By default, it is false, and requests to localhost are not sent through the upstream proxy.
Environment variable: SAUCE_PROXY_LOCALHOST
Shorthand: n/a

`--proxy-tunnel`

| OPTIONAL | 4.8.x 4.9.x |

Description: Routes all tunnel traffic through the external proxy specified by --proxy. Uses the proxy configured with --proxy or --pac for the tunnel connection. For more information about the -T option and configuring Sauce Connect Proxy with other proxies, see Set Up with Additional Proxies. You'll need to use this option if you have a PAC file that contains Sauce Labs DNS names.
Environment variable: SAUCE_PROXY_TUNNEL
Shorthand: -T

`--proxy-userpwd`

| OPTIONAL | STRING | 4.8.x 4.9.x |

Description: Sets username and password (sent via basic authentication) to access the proxy configured with --proxy. For more information, see Set Up with Additional Proxies.
Environment variable: SAUCE_PROXY_USERPWD
Shorthand: -w

Client Configuration

`--logfile`

| OPTIONAL | STRING | 4.8.x 4.9.x |

Description: Captures the Sauce Connect Proxy logs in a file. If a path is not specified, the file location will default to the location where the Sauce Connect Proxy executable can be found on your machine.
Environment variable: SAUCE_LOGFILE
Shorthand: -l

note

Use --logfile - to print your log to the console window (stdout) instead of the physical log file.

`--max-logsize`

| OPTIONAL | NUMBER | 4.8.x 4.9.x |

Description: Rotates logfile after reaching the max bytes size. It creates a new log and appends an order number to the previous log. Disabled by default.
Environment variable: SAUCE_MAX_LOGSIZE
Shorthand: n/a

`--output-format`

| OPTIONAL | STRING | 4.8.x 4.9.x |

Description: Specifies console output format. You can configure either pretty output, which will display various fonts and graphics, or text (text only). Default: pretty.
Environment variable: SAUCE_OUTPUT_FORMAT
Shorthand: n/a

`--pidfile`

| OPTIONAL | STRING | 4.8.x 4.9.x |

Description: Specifies the file where you want the Sauce Connect Proxy process ID (pid) to be written. This is useful for programmatically stopping Sauce Connect Proxy. Although Sauce Connect Proxy makes a best effort, we cannot guarantee that the pidfile will be removed when shutting down Sauce Connect Proxy. With that in mind, relying on the pidfile as a means to monitor Sauce Connect Proxy is not supported.
Environment variable: SAUCE_PIDFILE
Shorthand: -d

`--readyfile`

| OPTIONAL | STRING | 4.8.x 4.9.x |

Description: Sets file that is updated when the tunnel is ready. See also Using ready file with Docker.
Environment variable: SAUCE_READYFILE
Shorthand: -f

`--scproxy-port`

| OPTIONAL | NUMBER | 4.8.x 4.9.x |

Description: Sets port to use for the built-in HTTP proxy.
Environment variable: SAUCE_SCPROXY_PORT
Shorthand: -X

`--status-address`

| OPTIONAL | STRING | 4.8.x 4.9.x |

Description: Use this option to define the host:port for the internal web server used to expose the Sauce Connect Proxy runtime info. See the Sauce Connect Proxy Monitoring for more info. Disabled by default.
Environment variable: SAUCE_STATUS_ADDRESS
Shorthand: n/a

`--se-port`

| OPTIONAL | NUMBER | 4.8.x 4.9.x |

Description: Sets the port on which Sauce Connect Proxy's Selenium relay will listen for requests. Selenium commands reaching Sauce Connect Proxy on this port will be relayed to Sauce Labs securely and reliably through Sauce Connect Proxy's tunnel. This feature is disabled unless specified. For more information, see Using the Selenium Relay.
Environment variable: SAUCE_SE_PORT
Shorthand: -P

Networking and Security

`--auth`

| OPTIONAL | STRING | 4.8.x 4.9.x |

Description: Performs basic authentication when a URL on host:port asks for a username and password (host:port:username:password format). This option can be used multiple times. For examples, see Authentication Using --auth.

This flag will only send the header Authorization with a type of "Basic." If a resource responds with the header WWW-Authenticate of a type any other than "Basic," your authentication will fail and return a non-200 HTTP response. HTTP Header Injection is disabled for SSL domains that are not re-encrypted by Sauce Connect Proxy, which means performing basic authentication in this way is disabled for all HTTPS domains passed to --no-ssl-bump-domains argument.
Environment variable: SAUCE_AUTH
Shorthand: -a

--auth mysite.com:80:awesometester:supersekrit

`--cainfo`

| OPTIONAL | STRING | 4.8.x 4.9.x |

Description: CA certificate bundle in PEM format to use for verifying connections to Sauce Labs REST API. Default: /private/etc/ssl/cert.pem. This is normally used when a proxy is needed to access the REST API, and the proxy's certificate isn't available in the system certificate store. This does not affect test traffic through Sauce Connect.
Environment variable: SAUCE_CAINFO
Shorthand: n/a

`--dns`

| OPTIONAL | STRING | 4.8.x 4.9.x |

Description: Uses specified name server. To specify multiple servers, separate them with a comma. Use IP addresses, optionally with a port number, the two separated by a colon.
Environment variable: SAUCE_DNS
Shorthand: n/a

--dns 8.8.8.8,8.8.4.4:53

`--tunnel-cainfo`

| OPTIONAL | STRING | 4.8.x 4.9.x |

Description: CA certificate bundle in PEM format to use for verifying tunnel connections. This is normally used when a proxy is needed to access the tunnel endpoint, and the proxy's certificate isn't available in the system certificate store. This does not affect test traffic through Sauce Connect.
Environment variable: SAUCE_TUNNEL_CAINFO
Shorthand: n/a

`--ocsp`

| OPTIONAL | STRING | 4.8.x 4.9.x |

Description: OCSP verification mode. Options are: strict, log-only, and disable. The default is log-only.
Environment variable: SAUCE_OCSP
Shorthand: n/a

note

--ocsp strict may fail if a certificate in the chain does not support OCSP. We recommend leaving it as the default "log-only" mode.

Troubleshooting and Debugging

`--log-stats`

| OPTIONAL | BOOLEAN | 4.8.x |

Description: Logs statistics about HTTP traffic every <seconds>. Information includes bytes transmitted, requests made, and responses received.
Environment variable: SAUCE_LOG_STATS
Shorthand: -z

`--verbose`

| OPTIONAL | NUMBER | 4.8.x 4.9.x |

Description: Enables verbose debugging. Use this to log HTTP headers or debug Sauce Connect connection. You can also use -vv (very verbose), which outputs HTTP headers and KGP logs, although it's recommended for troubleshooting purposes only because it's system-resource demanding and can adversely affect Sauce Connect Proxy performance.
Environment variable: SAUCE_VERBOSE
Shorthand: -v

note

Setting the SAUCE_VERBOSE environment variable to 1 is equivalent to -v and 2 is equivalent to -vv.

Other Options

`--experimental`

| OPTIONAL | STRING | 4.8.x 4.9.x |

Description: Enable or disable experimental features. This flag allows controlled replacement of the components. It should only be used if the default feature configuration exhibits undesired behavior.

Option	Description	Example	Available in Versions
`proxy`	Use the new scproxy implementation (default).	`--experimental proxy`	4.8.x
`no-proxy`	Use the previous generation scproxy.	`--experimental no-proxy`	4.8.x

Environment variable: SAUCE_EXPERIMENTAL
Shorthand: n/a

Formatting Domains

Here are some guidelines to follow when formatting domains:

Use only the domain name. Do not precede it with http: or https:.
- Example: mydomain.com
Make sure your comma-separated list of domains doesn't include any spaces.
- Example, mydomain.com,saucelabs.com,mysite.com
Prefix domain names with a dot . to match all its subdomains.
- Example: You could refer to docs.saucelabs.com and my.saucelabs.com as "*.saucelabs.com" or ".saucelabs.com". Enclose the argument in quotes to prevent shell expansion of asterisk.
If you don't want any domains to be SSL re-encrypted, you can specify all with the argument (that is, -B all or --no-ssl-bump-domains all)
WebSockets domains are not compatible with SSL bumping, so you'll need to disable SSL Bumping for those.

What You'll Need​

Main​

--user​

--api-key​

--config-file​

--region​

--rest-url​

--shared-tunnel​

--tunnel-identifier​

--tunnel-name​

--tunnel-pool​

Tunnel Configuration​

--direct-domains​

--no-ssl-bump-domains​

--fast-fail-regexps​

--tunnel-domains​

--extra-info​

External Proxy Configuration​

--autodetect​

--no-autodetect​

--pac​

--pac-auth​

--proxy​

--proxy-localhost​

--proxy-tunnel​

--proxy-userpwd​

Client Configuration​

--logfile​

--max-logsize​

--output-format​

--pidfile​

--readyfile​

--scproxy-port​

--status-address​

--se-port​

Networking and Security​

--auth​

--cainfo​

--dns​

--tunnel-cainfo​

--ocsp​

Troubleshooting and Debugging​

--log-stats​

--verbose​

Other Options​

--experimental​

Formatting Domains​

Additional Resources​

What You'll Need

Main

`--user`

`--api-key`

`--config-file`

`--region`

`--rest-url`

`--shared-tunnel`

`--tunnel-identifier`

`--tunnel-name`

`--tunnel-pool`

Tunnel Configuration

`--direct-domains`

`--no-ssl-bump-domains`

`--fast-fail-regexps`

`--tunnel-domains`

`--extra-info`

External Proxy Configuration

`--autodetect`

`--no-autodetect`

`--pac`

`--pac-auth`

`--proxy`

`--proxy-localhost`

`--proxy-tunnel`

`--proxy-userpwd`

Client Configuration

`--logfile`

`--max-logsize`

`--output-format`

`--pidfile`

`--readyfile`

`--scproxy-port`

`--status-address`

`--se-port`

Networking and Security

`--auth`

`--cainfo`

`--dns`

`--tunnel-cainfo`

`--ocsp`

Troubleshooting and Debugging

`--log-stats`

`--verbose`

Other Options

`--experimental`

Formatting Domains

Additional Resources