You are reading the docs for rws 18.6 The latest release is 18.8. Read this page for the latest release.

CLI Arguments

All command-line flags accepted by rust-web-server, with types, defaults, and examples.

Command-line arguments are the highest-priority configuration layer — they override defaults, system environment variables, and rws.config.toml. Every flag maps directly to a RWS_CONFIG_* environment variable; setting the flag is exactly equivalent to setting that variable before the process starts.

Flags use the --long-form=value syntax. A single-character short form is also supported with -x=value.

rws [--flag=value ...]

Server

Flag Short Type Default Maps to
--ip=<addr> -i string 0.0.0.0 RWS_CONFIG_IP
--port=<n> -p integer 7878 RWS_CONFIG_PORT
--thread-count=<n> -t integer 200 RWS_CONFIG_THREAD_COUNT
--request-allocation-size-in-bytes=<n> -r integer 10000 RWS_CONFIG_REQUEST_ALLOCATION_SIZE_IN_BYTES 
# Listen on all interfaces on port 443 with 500 worker threads
rws --ip=0.0.0.0 --port=443 --thread-count=500

TLS

Flag Short Type Default Maps to
--tls-cert-file=<path> -s path `` (empty) RWS_CONFIG_TLS_CERT_FILE
--tls-key-file=<path> -k path `` (empty) RWS_CONFIG_TLS_KEY_FILE

Setting both --tls-cert-file and --tls-key-file enables HTTPS, HTTP/2, and HTTP/3. The server falls back to plain HTTP/1.1 when either flag is absent.

rws --tls-cert-file=cert.pem --tls-key-file=key.pem
Flag Short Type Default Maps to
--http-redirect-port=<n> — integer `` (empty) RWS_CONFIG_HTTP_REDIRECT_PORT
mTLS

RWS_CONFIG_TLS_CLIENT_CA_FILE has no CLI flag. Set it via the environment variable or tls_client_ca_file in rws.config.toml.

ACME

Long form only (acme feature). See Automatic HTTPS.

Flag Type Default Maps to
--acme-domains=<list> string `` (empty) RWS_CONFIG_ACME_DOMAINS
--acme-email=<addr> string `` (empty) RWS_CONFIG_ACME_EMAIL
--acme-staging=<bool> bool false RWS_CONFIG_ACME_STAGING
--acme-directory=<url> string `` (empty) RWS_CONFIG_ACME_DIRECTORY
--acme-ca-file=<path> path `` (empty) RWS_CONFIG_ACME_CA_FILE
--acme-challenge-port=<n> integer 80 RWS_CONFIG_ACME_CHALLENGE_PORT
--acme-cert-path=<path> path `` (empty) RWS_CONFIG_ACME_CERT_PATH
--acme-key-path=<path> path `` (empty) RWS_CONFIG_ACME_KEY_PATH
--acme-profile=<name> string `` (empty) RWS_CONFIG_ACME_PROFILE

Settings not listed on this page have no flag; set them through the environment or rws.config.toml.

CORS

Flag Short Type Default Maps to
--cors-allow-all=<bool> -a bool false RWS_CONFIG_CORS_ALLOW_ALL
--cors-allow-origins=<list> -o string `` (empty) RWS_CONFIG_CORS_ALLOW_ORIGINS
--cors-allow-methods=<list> -m string `` (empty) RWS_CONFIG_CORS_ALLOW_METHODS
--cors-allow-headers=<list> -h string `` (empty) RWS_CONFIG_CORS_ALLOW_HEADERS
--cors-allow-credentials=<bool> -c bool `` (empty) RWS_CONFIG_CORS_ALLOW_CREDENTIALS
--cors-expose-headers=<list> -e string `` (empty) RWS_CONFIG_CORS_EXPOSE_HEADERS
--cors-max-age=<seconds> -g integer 86400 RWS_CONFIG_CORS_MAX_AGE

<list> values are comma-separated strings. Header name lists should be lowercase.

# Disable the allow-all default and restrict to specific origins
rws \
  --cors-allow-all=false \
  --cors-allow-origins=https://app.example.com,https://admin.example.com \
  --cors-allow-methods=GET,POST,PUT,DELETE \
  --cors-allow-headers=content-type,authorization \
  --cors-allow-credentials=true \
  --cors-expose-headers=x-request-id \
  --cors-max-age=3600
 allow-all takes precedence

When --cors-allow-all=true (the default), the specific --cors-allow-origins, --cors-allow-methods, and --cors-allow-headers flags are ignored. Set --cors-allow-all=false to activate fine-grained CORS control.

Informational flags

These print and exit without starting the server.

Flag What it does
--version, -V Print rws <version>
--help Print usage and every flag with its environment variable
--check[=<file>] Validate the config file (default: RWS_CONFIG_FILE, else ./rws.config.toml); exit 0 if no errors, 1 otherwise
--format=json With --check, print the report as JSON

--windows-service=<directory> (Windows) runs rws as a service of the Service Control Manager, serving <directory> — see Windows.

Quick-start examples

Development server (HTTP only)

cargo run -- --ip=127.0.0.1 --port=7878

HTTPS with HTTP/2 and HTTP/3

cargo run -- --tls-cert-file=cert.pem --tls-key-file=key.pem

Locked-down CORS for production

rws \
  --port=443 \
  --tls-cert-file=/etc/ssl/server.pem \
  --tls-key-file=/etc/ssl/server.key \
  --cors-allow-all=false \
  --cors-allow-origins=https://app.example.com \
  --cors-allow-methods=GET,POST \
  --cors-allow-headers=content-type,authorization \
  --request-allocation-size-in-bytes=65536

Override a single value from the config file

CLI flags always win over rws.config.toml. Use this pattern to temporarily change a setting without editing the file:

# rws.config.toml has port = 7878; override to 9090 for this run only
rws --port=9090

Full flag reference

rws [OPTIONS]

OPTIONS:
  -i, --ip=<addr>
        IP address to bind (default: 0.0.0.0)

  -p, --port=<n>
        TCP port to listen on (default: 7878)

  -t, --thread-count=<n>
        Worker thread pool size (http1 build only; default: 200)

  -r, --request-allocation-size-in-bytes=<n>
        Read buffer size per request in bytes (default: 10000)

  -s, --tls-cert-file=<path>
        Path to PEM certificate chain; enables TLS when set

  -k, --tls-key-file=<path>
        Path to PEM private key; enables TLS when set

  -a, --cors-allow-all=<bool>
        Allow all CORS origins (default: true)

  -o, --cors-allow-origins=<list>
        Comma-separated allowed origins

  -m, --cors-allow-methods=<list>
        Comma-separated allowed HTTP methods

  -h, --cors-allow-headers=<list>
        Comma-separated allowed request headers (lowercase)

  -c, --cors-allow-credentials=<bool>
        Allow credentials in CORS requests

  -e, --cors-expose-headers=<list>
        Comma-separated response headers exposed to the browser (lowercase)

  -g, --cors-max-age=<seconds>
        Preflight cache duration in seconds (default: 86400)

      --http-redirect-port=<n>
        Plain-HTTP port that 301-redirects to HTTPS (and answers ACME HTTP-01)

      --acme-domains, --acme-email, --acme-staging, --acme-directory,
      --acme-ca-file, --acme-challenge-port, --acme-cert-path, --acme-key-path,
      --acme-profile
        ACME settings (see above)

  -V, --version          Print the version and exit
      --help             Print usage and exit
      --check[=<file>]   Validate the configuration and exit (--format=json for JSON)
      --windows-service=<dir>
                         (Windows) Run as a service serving <dir>

Edit this page on GitHub