Skip to main content

​
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

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: 
# 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

Build docs developers (and LLMs) love

Get started for freeTalk to us