TrustTunnel CLI Client is an application built on top of the TrustTunnel Client Libraries. It provides an easy-to-use interface to configure and connect to a TrustTunnel endpoint. The client supports Linux, macOS, and Windows platforms.

To build the TrustTunnel CLI Client, follow development instructions. The built executable will be available in the <project_root>/build/trusttunnel_client directory.

The TrustTunnel CLI Client accepts a TOML-formatted configuration file. You can use the setup wizard tool to generate a basic configuration file.

For quick setup, please follow Getting Started instructions.

For a more customized configuration experience, follow the steps below:

1. Build the setup wizard tool.

2. Launch the setup wizard:

   ./setup_wizard

   The setup wizard will guide you through the configuration process, allowing you to customize the settings according to your preferences.

Note: The configuration file created by the setup wizard contains all available settings, including descriptions. Feel free to modify them if you have a good understanding of the configuration.

Usage: setup_wizard [OPTIONS]

Options:
  -m, --mode <mode>           Wizard running mode [default: interactive]
                              * interactive - guided setup with prompts
                              * non-interactive - automated setup from CLI args
  -a, --address <address>     Endpoint address (can be specified multiple times)
  -n, --hostname <host>       Endpoint hostname for TLS session
  -c, --creds <creds>         Credentials as <username>:<password>
      --cert <cert>           Path to endpoint certificate file
      --settings <settings>   Output path for settings file (required in non-interactive mode)
  -e, --endpoint_config <path>
                              Path to config generated by endpoint (conflicts with -a, -n, -c)
  -h, --help                  Print help

Interactive mode (guided setup):

./setup_wizard

Non-interactive with endpoint config (recommended):

./setup_wizard --mode non-interactive \
    --endpoint_config <endpoint_config.toml> \
    --settings trusttunnel_client.toml

Non-interactive with manual parameters:

./setup_wizard --mode non-interactive \
    --address 192.168.1.100:443 \
    --hostname vpn.example.com \
    --creds myuser:mypassword \
    --cert server.pem \
    --settings trusttunnel_client.toml

The configuration file uses TOML format. Below are all available settings.

The exclusions array supports the following formats:

• Domain name: example.com — matches example.com and www.example.com
• Wildcard domain: *.example.com — matches any subdomain (e.g., sub.example.com), but not the domain itself
• IPv4 address: 192.168.1.1 or 192.168.1.1:443 (port optional)
• IPv6 address: [::1] or [::1]:443 or 2001:db8::1
• CIDR range: 192.168.0.0/16 or 2001:db8::/32

The dns_upstreams array supports the following formats:

• Plain DNS: 8.8.8.8:53
• DNS over TCP: tcp://8.8.8.8:53
• DNS over TLS: tls://1.1.1.1
• DNS over HTTPS: https://dns.adguard.com/dns-query
• DNS over QUIC: quic://dns.adguard.com:8853
• DNS Stamp: sdns://... (see DNS Stamps specification)

loglevel = "info"
vpn_mode = "general"
killswitch_enabled = true
killswitch_allow_ports = []
post_quantum_group_enabled = true
exclusions = []

[endpoint]
hostname = "vpn.example.com"
addresses = ["192.168.1.100:443"]
has_ipv6 = true
username = "myuser"
password = "mypassword"
client_random = ""
skip_verification = false
certificate = ""
dns_upstreams = ["tls://1.1.1.1"]
upstream_protocol = "http2"
anti_dpi = false

[listener.tun]
bound_if = ""
included_routes = ["0.0.0.0/0", "2000::/3"]
excluded_routes = ["10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"]
mtu_size = 1280

Windows specific: For tunnel listener to work, wintun.dll must be in the DLL search path. Basically, you could download it, extract the file (from the folder matching your architecture, like amd64) and place it into the same directory as trusttunnel_client executable.

To run the TrustTunnel CLI Client, execute the following command:

./trusttunnel_client --config <path/to/configuration/file.toml>

Replace <path/to/configuration/file.toml> with the actual path to your configuration file. You may need to run the command with superuser privileges if a TUN device is selected.

The TrustTunnel CLI Client can be installed as a Windows service, allowing it to run in the background without requiring an interactive console session.

Note: Both install and uninstall commands require Administrator privileges. Run the command from an elevated Command Prompt or PowerShell.

trusttunnel_client --service-install --config <path/to/trusttunnel_client.toml>

The command validates the configuration file before registering the service. If validation fails, the service is not installed. The config path is resolved to an absolute path and baked into the service registration — the service will always start with that config file.

The service is registered with automatic start type (SERVICE_AUTO_START) and is started immediately after installation.

After installation, use the standard Windows service management commands:

cmd.exe:

sc start TrustTunnelClient
sc stop TrustTunnelClient

PowerShell:

Start-Service TrustTunnelClient
Stop-Service TrustTunnelClient

cmd.exe:

sc query TrustTunnelClient

PowerShell:

Get-Service TrustTunnelClient

To switch the service to manual start:

cmd.exe:

sc config TrustTunnelClient start= demand

PowerShell:

Set-Service TrustTunnelClient -StartupType Manual

trusttunnel_client --service-uninstall

If the service is currently running, it will be stopped automatically before removal.

• If the configuration file is moved or deleted after installation, the service will fail to start. Reinstall the service with the new config path.
• The --service-install and --service-uninstall options are only available on Windows builds.