Skip to main content

Sauce Connect Proxy CLI Reference

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

What You'll Need

tip

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


Main


--user

| REQUIRED | STRING | 4.6.x 4.7.x 4.8.x|

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


--api-key

| REQUIRED | STRING | 4.6.x 4.7.x 4.8.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.
Enviroment variable: SAUCE_ACCESS_KEY or SAUCE_API_KEY
Shorthand: -k


--config-file

| OPTIONAL | STRING | 4.6.x 4.7.x 4.8.x|

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

caution

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


--region

| OPTIONAL | STRING | 4.7.x 4.8.x|

Description: Sets your Sauce Labs data center endpoint (e.g., us-west, eu-central, apac-southeast).
Default: If you don't specify a data center, Sauce Connect will default to us-west.
Enviroment variable: SAUCE_REGION
Shorthand: -r

#US-West-1
./sc -u $SAUCE_USERNAME -k $SAUCE_ACCESS_KEY --region us-west

#EU-Central-1
./sc -u $SAUCE_USERNAME -k $SAUCE_ACCESS_KEY --region eu-central

#APAC-Southeast-1
./sc -u $SAUCE_USERNAME -k $SAUCE_ACCESS_KEY --region apac-southeast

--shared-tunnel

| OPTIONAL | 4.6.x 4.7.x 4.8.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.
Enviroment variable: SAUCE_SHARED_TUNNEL
Shorthand: -s


--tunnel-identifier

| OPTIONAL | STRING | 4.6.x 4.7.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.
Enviroment 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). In Sauce Connect v4.7.0 and later, you can use the --tunnel-identifier or --tunnel-name flags interchangeably.


--tunnel-name

| OPTIONAL | STRING | 4.7.x 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.
Enviroment variable: SAUCE_TUNNEL_NAME
Shorthand: -i


--tunnel-pool

| OPTIONAL | STRING | 4.7.x 4.8.x|

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

Tunnel Configuration


--direct-domains

| OPTIONAL | STRING | 4.6.x 4.7.x 4.8.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.
Enviroment variable: SAUCE_DIRECT_DOMAINS
Shorthand: -D


--no-ssl-bump-domains

| OPTIONAL | STRING | 4.6.x 4.7.x 4.8.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.
Enviroment variable: SAUCE_NO_SSL_BUMP_DOMAINS
Shorthand: -B

note

HTTP Header Injection is disabled for all HTTPS domains passed to the --no-ssl-bump-domains argument.


--fast-fail-regexps

| OPTIONAL | STRING | 4.6.x 4.7.x 4.8.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.
Enviroment variable: SAUCE_FAST_FAIL_REGEXPS
Shorthand: -F


--tunnel-domains

| OPTIONAL | STRING | 4.6.x 4.7.x 4.8.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.
Enviroment variable: SAUCE_TUNNEL_DOMAINS
Shorthand: -t


--rest-url

| OPTIONAL | STRING | 4.6.x 4.7.x 4.8.x|

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

#US-West-1
./sc -u $SAUCE_USERNAME -k $SAUCE_ACCESS_KEY -x https://api.us-west-1.saucelabs.com/rest/v1

#EU-Central-1
./sc -u $SAUCE_USERNAME -k $SAUCE_ACCESS_KEY -x https://api.eu-central-1.saucelabs.com/rest/v1

#APAC-Southeast-1
./sc -u $SAUCE_USERNAME -k $SAUCE_ACCESS_KEY -x https://api.apac-southeast-1.saucelabs.com/rest/v1
note

Effective with version 4.7.0, this flag was deprecated and replaced by --region.


--no-remove-colliding-tunnels

| OPTIONAL | 4.6.x|

Description: Prevents the removal of colliding tunnels (i.e., tunnels with the same name).
Enviroment variable: n/a

note

Effective with version 4.7.0, this flag was deprecated and replaced by --tunnel-pool.

External Proxy Configuration


--autodetect

| OPTIONAL | BOOLEAN | 4.8.x|

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


--no-autodetect

| OPTIONAL | BOOLEAN | 4.6.x 4.7.x 4.8.x|

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


--pac

| OPTIONAL | STRING | 4.6.x 4.7.x 4.8.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. For more information, see Sauce Connect Proxy Setup with Additional Proxies.
Enviroment variable: SAUCE_PAC
Shorthand: n/a

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

--pac-auth

| OPTIONAL | STRING | 4.6.x 4.7.x 4.8.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.
Enviroment variable: SAUCE_PAC_AUTH
Shorthand: n/a


--proxy

| OPTIONAL | STRING | 4.6.x 4.7.x 4.8.x|

Description: Defines external proxy host:port where you want to route Sauce Labs REST API bound traffic.
Enviroment variable: SAUCE_PROXY
Shorthand: -p


--proxy-localhost

| OPTIONAL | BOOLEAN | 4.7.x 4.8.x|

Description: Setting this to true supports proxying upstream requests to localhost. This includes scenarios where an upstream proxy is hosted on localhost. By default, it is false.
Enviroment variable: SAUCE_PROXY_LOCALHOST
Shorthand: n/a


--proxy-tunnel

| OPTIONAL | 4.6.x 4.7.x 4.8.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.
Enviroment variable: SAUCE_PROXY_TUNNEL
Shorthand: -T


--proxy-userpwd

| OPTIONAL | STRING | 4.6.x 4.7.x 4.8.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.
Enviroment variable: SAUCE_PROXY_USERPWD
Shorthand: -w

Client Configuration


--logfile

| OPTIONAL | STRING | 4.6.x 4.7.x 4.8.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.
Enviroment 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.6.x 4.7.x 4.8.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.
Enviroment variable: SAUCE_MAX_LOGSIZE
Shorthand: n/a


--output-format

| OPTIONAL | STRING | 4.8.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.
Enviroment variable: SAUCE_OUTPUT_FORMAT
Shorthand: n/a


--pidfile

| OPTIONAL | STRING | 4.6.x 4.7.x 4.8.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.
Enviroment variable: SAUCE_PIDFILE
Shorthand: -d


--readyfile

| OPTIONAL | STRING | 4.6.x 4.7.x 4.8.x|

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


--scproxy-port

| OPTIONAL | NUMBER | 4.6.x 4.7.x 4.8.x|

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


--se-port

| OPTIONAL | NUMBER | 4.6.x 4.7.x 4.8.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.
Enviroment variable: SAUCE_SE_PORT
Shorthand: -P

Networking and Security


--auth

| OPTIONAL | STRING | 4.6.x 4.7.x 4.8.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.
Enviroment variable: SAUCE_AUTH
Shorthand: -a

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

--cainfo

| OPTIONAL | STRING | 4.6.x 4.7.x 4.8.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.
Enviroment variable: SAUCE_CAINFO
Shorthand: n/a


--dns

| OPTIONAL | STRING | 4.6.x 4.7.x 4.8.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.
Enviroment variable: SAUCE_DNS
Shorthand: n/a

--dns 8.8.8.8,8.8.4.4:53

--tunnel-cainfo

| OPTIONAL | STRING | 4.6.x 4.7.x 4.8.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.
Enviroment variable: SAUCE_TUNNEL_CAINFO
Shorthand: n/a


--ocsp

| OPTIONAL | STRING | 4.6.x 4.7.x 4.8.x|

Description: OCSP verification mode. Options are: strict, log-only, and disable. The default is log-only.
Enviroment 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.


--tunnel-capath

| OPTIONAL | 4.6.x|

Description: Directory of CA certificates to use for verifying tunnel connections.
Enviroment variable: n/a
Shorthand: n/a


--capath

| OPTIONAL | 4.6.x|

Description: Defines a directory of CA certs to use for verifying connections to Sauce Labs REST API.
Enviroment variable: n/a
Shorthand: n/a

Troubleshooting and Debugging


--log-stats

| OPTIONAL | BOOLEAN | 4.6.x 4.7.x|

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


--metrics-address

| OPTIONAL | STRING | 4.6.x 4.7.x|

Description: Use this option to define the host:port for the internal web server used to expose client-side metrics. Disabled by default.
Enviroment variable: SAUCE_METRICS_ADDRESS
Shorthand: n/a

note

Effective with version 4.8.0, this flag was deprecated and replaced by --status-address.


--status-address

| OPTIONAL | STRING | 4.8.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.
Enviroment variable: SAUCE_STATUS_ADDRESS
Shorthand: n/a


--verbose

| OPTIONAL | 4.6.x 4.7.x 4.8.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.
Enviroment variable: SAUCE_VERBOSE
Shorthand: -v

Other Options


--scproxy-read-limit

| OPTIONAL | NUMBER | 4.6.x 4.7.x 4.8.x|

Description: Rates limit reads in scproxy to the number of bytes per second that you specify. This option can be used to adjust local network transfer rate to prevent overloading the tunnel connection.
Enviroment variable: SAUCE_SCPROXY_READ_LIMIT
Shorthand: n/a


--scproxy-write-limit

| OPTIONAL | NUMBER | 4.6.x 4.7.x 4.8.x|

Description: Rates limit writes in scproxy to the number of bytes per second that you specify. This option can be used to adjust local network transfer rate to prevent overloading the tunnel connection.
Enviroment variable: SAUCE_SCPROXY_WRITE_LIMIT
Shorthand: n/a


--experimental

| OPTIONAL | STRING | 4.8.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.

OptionDescriptionExample
proxyUse the new scproxy implementation (default).--experimental proxy
no-proxyUse the previous generation scproxy.--experimental no-proxy

Enviroment variable: SAUCE_EXPERIMENTAL
Shorthand: n/a


--extra-info

| OPTIONAL | STRING | 4.6.x 4.7.x 4.8.x|

Description: JSON string that contains an advanced tunnel configuration.

OptionDescriptionExample
inject-forwarded-forDo not remove X-FORWARDED-FOR header from the proxied HTTP requests.--extra-info '{"inject-forwarded-for": true}'
reply_body_max_sizeSet 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"}'

Enviroment variable: SAUCE_EXTRA_INFO
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 (i.e., -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.

Additional Resources