Command Line Parameters

TIP

Xray uses Go-style commands and parameters.

Getting Basic Commands

You can run xray help to get the most basic usage of Xray, as well as available commands and descriptions.

Xray is a platform for building proxies.

Usage:

        xray <command> [arguments]

The commands are:

        run          Run Xray with config, the default command
        version      Show current version of Xray
        api          Call an API in an Xray process
        convert      Convert configs
        tls          TLS tools
        uuid         Generate UUIDv4 or UUIDv5 (VLESS)
        x25519       Generate key pair for X25519 key exchange (REALITY, VLESS Encryption)
        wg           Generate key pair for X25519 key exchange (WireGuard)
        mldsa65      Generate key pair for ML-DSA-65 post-quantum signature (REALITY)
        mlkem768     Generate key pair for ML-KEM-768 post-quantum key exchange (VLESS Encryption)
        vlessenc     Generate decryption/encryption json pair (VLESS Encryption)

Use "xray help <command>" for more information about a command.

xray run

Specify one or more configuration files and run.

Usage:

xray run [-c config.json] [-confdir dir] [-format auto|json|yaml|toml|protobuf] [-test] [-dump] [-json-to-yaml] [-yaml-to-json] [-src file|dir] [-dst file|dir] [-yaml-flip n] [-yaml-no-alias] [-multi]

Flags:

-config= / -c=

Specify one or more config files (repeatable). With -format=auto (default), Xray detects the format by file extension:

• *.json / *.jsonc -> JSON (jsonc allows comments)
• *.yaml / *.yml -> YAML
• *.toml -> TOML
• *.pb -> Protobuf (single file only)

-confdir=

Specify a directory containing multiple config files. Xray loads files in filename order and merges them (see Multiple Config Files).

WARNING

If confdir contains both JSON (*.json/*.jsonc) and YAML (*.yaml/*.yml) files, Xray will fail fast.

-format=

Config format: auto (default), json, yaml, toml, protobuf. When set to a non-auto value, all -c/-config files will be parsed as that format.

-test

Test the configuration only (loads config and creates the core instance, but does not start the server).

-dump

Print the merged config and exit (does not start the server). It also expands subscriptions (the subscription {} block is removed in the output). Note: -dump is meaningful for json/yaml/toml only.

-json-to-yaml

Output the merged config as YAML and exit (does not start the server). Requires both -src and -dst. Similar to -dump, it also expands subscriptions (the subscription {} block is removed in the output).

The default output is block style (-yaml-flip=0) to avoid flow-style {} where possible.

Examples:

# Recommended: specify input/output (file or directory)
xray --json-to-yaml --src config.json --dst config.yaml

# Output to a directory (writes out/config.yaml)
xray --json-to-yaml --src config.json --dst ./out

# Source is a directory (confdir), output to a directory (writes out/config.yaml)
xray --json-to-yaml --src ./confs --dst ./out

# Read from STDIN (must explicitly set stdin:)
cat config.json | xray --json-to-yaml --src stdin: --dst config.yaml

Config Auto-Discovery

If no -c/-config is provided and no -confdir directory is supplied via flags/env, Xray will try:

• config.json / config.jsonc / config.toml / config.yaml / config.yml in the working directory
• config.json under the directory specified by xray.location.config (or XRAY_LOCATION_CONFIG)
• STDIN (equivalent to using stdin: as the config source)

 xray run -dump

Used to output the result after merging multi-file configurations.

xray version

Output Xray version, Golang version, and other information.

Usage:

 xray version

xray api

Call Xray's gRPC API. Needs to be enabled in the configuration file.

Usage:

xray api <command> [arguments]

        restartlogger Restart the logger
        stats         Get statistics
        statsquery    Query statistics
        statssys      Get system statistics
        adi           Add inbounds
        ado           Add outbounds
        rmi           Remove inbounds
        rmo           Remove outbounds

xray convert

Convert configuration files to protobuf or convert typedMessage to JSON.

Usage:

xray convert <command> [arguments]

The commands are:

        pb           Convert multiple json configs to protobuf
        json         Convert typedMessage to json

pb subcommand usage example:

# Usage: xray convert pb [-outpbfile out.pb] [-debug] [-type] [json file] [json file] ...

# Merge three configs into mix.pb
xray convert pb -outpbfile mix.pb c1.json c2.json c3.json

# Use -debug option to view the content of mix.pb
xray convert pb -debug mix.pb

# Start Xray-core using mix.pb
xray -c mix.pb

# Detailed instructions
xray help convert pb

json subcommand usage example:

# Usage: xray convert json [-type] [stdin:] [typedMessage file]

tmsg='{
  "type": "xray.proxy.shadowsocks.Account",
  "value": "CgMxMTEQBg=="
}'

echo ${tmsg} | xray convert json stdin:

# The output of the above command is:
'{
  "cipherType": "AES_256_GCM",
  "password": "111"
}'

# Detailed instructions
xray help convert json

xray tls

Some tools related to TLS.

Usage:

xray tls <command> [arguments]

        cert          Generate TLS certificates
        ping          Ping the domain with TLS handshake
        certChainHash Calculate TLS certificates hash.

xray uuid

Generate UUID.

Usage:

xray uuid [-i "example"]

xray x25519

Generate x25519 key pair.

Usage:

xray x25519 [-i "(base64.RawURLEncoding)" --std-encoding ]

xray wg

Generate WireGuard curve25519 key pair.

Usage:

xray wg [-i "(base64.StdEncoding)"]

xray mldsa65

Generate MLDSA-65 post-quantum signature key pair for REALITY.

Usage:

xray mldsa65 [-i "seed (base64.StdEncoding)"]

xray mlkem768

Generate ML-KEM-768 post-quantum key exchange key pair for VLESS Encryption.

Usage:

xray mlkem768 [-i "seed (base64.StdEncoding)"]

xray vlessenc

Generate encryption/decryption option content that can be directly used for VLESS Encryption. In the generated configuration, you can use either X25519 or ML-KEM-768 authentication method, but the server and client must use the same authentication method. The ephemeral key exchange remains post-quantum secure regardless of the authentication method.

Usage:

xray vlessenc