CLI

Complete reference for Traefik command-line interface commands, flags, and options

Command Line Interface

The Traefik command line interface provides commands and flags for managing and operating Traefik instances.

Overview

Traefik exposes its configuration through a CLI that supports multiple commands and flags. All configuration options can be set via command-line flags, environment variables, or configuration files.

Basic Usage

traefik [command] [flags] [arguments]

Use traefik [command] --help for detailed help on any command.

All flags are case-insensitive and can be used with either single dash (-flag) or double dash (--flag) notation.

Available Commands

Traefik provides the following commands:

Main Command

Running traefik without arguments starts the Traefik proxy with the default configuration:

traefik

With Config File

traefik --configFile=/etc/traefik/traefik.yml

healthcheck

Calls the Traefik /ping endpoint to check the health of the Traefik instance.

Description: Performs a health check by calling the /ping endpoint. Returns exit code 0 if healthy, 1 otherwise.

Usage:

traefik healthcheck [flags]

Examples:

# Basic health check
$ traefik healthcheck
OK: http://:8082/ping

# Health check with custom configuration
$ traefik healthcheck --configFile=/etc/traefik/traefik.yml
OK: http://localhost:8080/ping

The ping endpoint must be enabled in the static configuration for the healthcheck command to work. See Ping Documentation for configuration details.

Use Cases:

1. Docker Health Checks

   Use with Docker’s HEALTHCHECK instruction:

   FROM traefik:v3.2
   HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
     CMD traefik healthcheck || exit 1
   
2. Kubernetes Liveness Probes

   Configure as a Kubernetes liveness probe:

   livenessProbe:
     exec:
       command:
         - traefik
         - healthcheck
     initialDelaySeconds: 10
     periodSeconds: 30
   
3. Systemd Service Monitoring

   Monitor Traefik service health with systemd watchdog:

   # Check health before restart
   ExecStartPre=/usr/local/bin/traefik healthcheck
   

Source Reference: The healthcheck command is implemented in cmd/healthcheck/healthcheck.go:14-23

version

Displays the current Traefik version information.

Usage:

traefik version

Output:

Version:      v3.2.0
Codename:     Tatooine
Go version:   go1.23.1
Built:        2024-09-24T14:30:00Z
OS/Arch:      linux/amd64

Examples:

# Display version information
$ traefik version
Version:      v3.2.0
Codename:     Tatooine
Go version:   go1.23.1
Built:        2024-09-24T14:30:00Z
OS/Arch:      linux/amd64

# Use in scripts to check version
if traefik version | grep -q "v3.2"; then
  echo "Correct version installed"
fi

Source Reference: The version command is implemented in cmd/version/version.go:20-34

Common Flags

Configuration File

--configFile · string

Path to the configuration file. If specified, all other flags are ignored.

traefik --configFile=/etc/traefik/traefik.yml

Entry Points

--entrypoints.<name>.address · string

Define an entry point listening address.

# HTTP on port 80
traefik --entrypoints.web.address=:80

# HTTPS on port 443
traefik --entrypoints.websecure.address=:443

# Custom port
traefik --entrypoints.custom.address=:8080

--entrypoints.<name>.asDefault · boolean · default: "false"

Mark this entry point as a default entry point.

traefik --entrypoints.web.asDefault=true

Providers

--providers.docker · boolean · default: "false"

Enable Docker provider.

traefik --providers.docker=true --providers.docker.exposedByDefault=false

--providers.file.directory · string

Directory to watch for dynamic configuration files.

traefik --providers.file.directory=/etc/traefik/dynamic

--providers.file.filename · string

Path to a specific configuration file.

traefik --providers.file.filename=/etc/traefik/dynamic.yml

API and Dashboard

--api · boolean · default: "false"

Enable the API.

traefik --api=true

--api.dashboard · boolean · default: "true"

Enable the dashboard (requires API to be enabled).

traefik --api=true --api.dashboard=true

--api.insecure · boolean · default: "false"

Enable API in insecure mode (not recommended for production).

# Development only
traefik --api.insecure=true

--api.debug · boolean · default: "false"

Enable debug endpoints under /debug/.

traefik --api=true --api.debug=true

Ping

--ping · boolean · default: "false"

Enable the ping endpoint.

traefik --ping=true

--ping.entryPoint · string · default: "traefik"

Entry point to expose the ping endpoint.

traefik --ping=true --ping.entryPoint=web

Logging

--log.level · string · default: "ERROR"

Log level: DEBUG, INFO, WARN, ERROR, FATAL, PANIC.

traefik --log.level=DEBUG

--log.format · string · default: "common"

Log format: common or json.

traefik --log.format=json

--log.filePath · string

Path to log file. By default, logs are written to stdout.

traefik --log.filePath=/var/log/traefik/traefik.log

--accessLog · boolean · default: "false"

Enable access logs.

traefik --accessLog=true --accessLog.filePath=/var/log/traefik/access.log

Metrics

--metrics.prometheus · boolean · default: "false"

Enable Prometheus metrics.

traefik --metrics.prometheus=true

--metrics.prometheus.entryPoint · string · default: "traefik"

Entry point to expose Prometheus metrics.

traefik --metrics.prometheus=true --metrics.prometheus.entryPoint=metrics

Flag Syntax

Traefik supports multiple flag syntax formats:

Boolean Flags

# Set to true
traefik --flag
traefik --flag=true
traefik -f true

# Set to false
traefik --flag=false
traefik -f false

Environment Variables

All CLI flags can be set using environment variables with the prefix TRAEFIK_:

# Convert flag to environment variable
--flag.name=value → TRAEFIK_FLAG_NAME=value

# Examples
export TRAEFIK_ENTRYPOINTS_WEB_ADDRESS=:80
export TRAEFIK_PROVIDERS_DOCKER=true
export TRAEFIK_API_DASHBOARD=true
export TRAEFIK_LOG_LEVEL=DEBUG

traefik

Environment variables use underscores (_) instead of dots (.) and are always uppercase.

Configuration Priority

Traefik applies configuration in the following order (highest to lowest priority):

1. CLI Flags

   Flags passed directly on the command line.

   traefik --log.level=DEBUG
   
2. Environment Variables

   Environment variables with the TRAEFIK_ prefix.

   export TRAEFIK_LOG_LEVEL=DEBUG
   
3. Configuration File

   Settings in the static configuration file.

   log:
     level: DEBUG
   
4. Default Values

   Built-in default values.

Complete Example

Here’s a complete example combining multiple flags:

traefik \
  --entrypoints.web.address=:80 \
  --entrypoints.websecure.address=:443 \
  --providers.docker=true \
  --providers.docker.exposedByDefault=false \
  --providers.file.directory=/etc/traefik/dynamic \
  --api=true \
  --api.dashboard=true \
  --ping=true \
  --log.level=INFO \
  --log.format=json \
  --accessLog=true \
  --metrics.prometheus=true

Additional Resources

• API Documentation
• Ping Health Checks
• Dashboard Usage
• Deployment Guide