Skip to content
Reference
CLI reference

CLI reference

Sablier is configured through the sablier command. This page is generated from the command definitions, so it always matches the running binary. See Configuration for the configuration file search order.

Commands

Sablier exposes the following commands.

sablier health

Calls the health endpoint of a Sablier instance

--url

Sablier health endpoint

string
Default: http://localhost:10000/health

# Command-line flag
--url=http://localhost:10000/health

sablier start

Start the Sablier server

Every option in the sections below configures this command.

sablier version

Print the version Sablier

Setting an option

Every configuration option can be set three ways, in increasing precedence: configuration file, then environment variable, then command-line flag.

Option keys are dotted (for example strategy.dynamic.default-theme). In the configuration file, nest each segment. For the environment variable, upper-case the key, replace . and - with _, and add the SABLIER_ prefix. As a flag, pass the key verbatim with a -- prefix. Each option below shows all three forms.

Value types

  • string: any text value.
  • integer: a whole number.
  • number: a decimal number.
  • boolean: true or false.
  • duration: a Go duration string, e.g. 5m, 1m30s, 20s, 500ms.

General

OptionDescription
--configFileConfig file path.

--configFile

Config file path. If not defined, looks for sablier.(yml|yaml|toml) in /etc/sablier/ > $XDG_CONFIG_HOME > $HOME/.config/ and current directory

string
# Command-line flag
--configFile=<string>

Logging

OptionDescription
--logging.levelThe logging level.

--logging.level

The logging level. Can be one of [error, warn, info, debug]

string
Default: info
Since v1.0.0

Accepted values:

  • error
  • warn
  • info
  • debug
# sablier.yaml
logging:
  level: info
# Environment variable
SABLIER_LOGGING_LEVEL=info

# Command-line flag
--logging.level=info

Provider

OptionDescription
--provider.auto-stop-externally-startedContinuously stop instances with sablier.enable=true that are running but were not started by Sablier
--provider.auto-stop-on-startupStop all sablier.enable=true instances running at startup that were not started by Sablier
--provider.auto-warm-externally-startedContinuously create a default-duration session for instances with sablier.enable=true that are running but were not started by Sablier, instead of stopping them
--provider.docker.honor-restart-policyHonor the container restart policy on successful exit: report “no”/“on-failure” containers as completed and exited “always”/“unless-stopped” containers as stopped.
--provider.docker.strategyStrategy to use to stop docker containers (stop or pause)
--provider.kubernetes.burstMaximum burst for K8S API access client-side throttling
--provider.kubernetes.delimiterDelimiter used for namespace/resource type/name resolution.
--provider.kubernetes.qpsQPS limit for K8S API access client-side throttling
--provider.nameProvider to use to manage containers [docker docker_swarm swarm kubernetes podman proxmox_lxc]
--provider.podman.uriUri is the URI to connect to the Podman service.
--provider.proxmox-lxc.tls-insecureSkip TLS certificate verification for Proxmox VE API
--provider.proxmox-lxc.token-idProxmox VE API token ID (e.g. root@pam!sablier)
--provider.proxmox-lxc.token-secretProxmox VE API token secret
--provider.proxmox-lxc.urlProxmox VE API URL (e.g. https://proxmox:8006/api2/json)
--provider.reject-unlabeled-requestsReject direct named requests for instances without sablier.enable=true
--provider.verify-enabled-on-expirationVerify sablier.enable=true before stopping expired instances

--provider.auto-stop-externally-started

Continuously stop instances with sablier.enable=true that are running but were not started by Sablier

boolean
Default: false
Since v1.13.0

# sablier.yaml
provider:
  auto-stop-externally-started: false
# Environment variable
SABLIER_PROVIDER_AUTO_STOP_EXTERNALLY_STARTED=false

# Command-line flag
--provider.auto-stop-externally-started=false

--provider.auto-stop-on-startup

Stop all sablier.enable=true instances running at startup that were not started by Sablier

boolean
Default: true
Since v1.8.0

# sablier.yaml
provider:
  auto-stop-on-startup: true
# Environment variable
SABLIER_PROVIDER_AUTO_STOP_ON_STARTUP=true

# Command-line flag
--provider.auto-stop-on-startup=true

--provider.auto-warm-externally-started

Continuously create a default-duration session for instances with sablier.enable=true that are running but were not started by Sablier, instead of stopping them

boolean
Default: false
Next release

# sablier.yaml
provider:
  auto-warm-externally-started: false
# Environment variable
SABLIER_PROVIDER_AUTO_WARM_EXTERNALLY_STARTED=false

# Command-line flag
--provider.auto-warm-externally-started=false

--provider.docker.honor-restart-policy

Honor the container restart policy on successful exit: report “no”/“on-failure” containers as completed and exited “always”/“unless-stopped” containers as stopped. Deprecated: will become the default in v2.

boolean
Default: false
Next release

# sablier.yaml
provider:
  docker:
    honor-restart-policy: false
# Environment variable
SABLIER_PROVIDER_DOCKER_HONOR_RESTART_POLICY=false

# Command-line flag
--provider.docker.honor-restart-policy=false

--provider.docker.strategy

Strategy to use to stop docker containers (stop or pause)

string
Default: stop
Since v1.11.0

Accepted values:

  • stop
  • pause
# sablier.yaml
provider:
  docker:
    strategy: stop
# Environment variable
SABLIER_PROVIDER_DOCKER_STRATEGY=stop

# Command-line flag
--provider.docker.strategy=stop

--provider.kubernetes.burst

Maximum burst for K8S API access client-side throttling

integer
Default: 10
Since v1.4.1-beta.2

# sablier.yaml
provider:
  kubernetes:
    burst: 10
# Environment variable
SABLIER_PROVIDER_KUBERNETES_BURST=10

# Command-line flag
--provider.kubernetes.burst=10

--provider.kubernetes.delimiter

Delimiter used for namespace/resource type/name resolution. Defaults to “_” for backward compatibility. But you should use “/” or “.”

string
Default: _
Since v1.7.0

# sablier.yaml
provider:
  kubernetes:
    delimiter: _
# Environment variable
SABLIER_PROVIDER_KUBERNETES_DELIMITER=_

# Command-line flag
--provider.kubernetes.delimiter=_

--provider.kubernetes.qps

QPS limit for K8S API access client-side throttling

number
Default: 5
Since v1.4.1-beta.2

# sablier.yaml
provider:
  kubernetes:
    qps: 5
# Environment variable
SABLIER_PROVIDER_KUBERNETES_QPS=5

# Command-line flag
--provider.kubernetes.qps=5

--provider.name

Provider to use to manage containers [docker docker_swarm swarm kubernetes podman proxmox_lxc]

string
Default: docker
Since v1.0.0

Accepted values:

  • docker
  • docker_swarm
  • swarm
  • kubernetes
  • podman
  • proxmox_lxc
# sablier.yaml
provider:
  name: docker
# Environment variable
SABLIER_PROVIDER_NAME=docker

# Command-line flag
--provider.name=docker

--provider.podman.uri

Uri is the URI to connect to the Podman service.

string
Default: unix:///run/podman/podman.sock
Since v1.10.0

# sablier.yaml
provider:
  podman:
    uri: unix:///run/podman/podman.sock
# Environment variable
SABLIER_PROVIDER_PODMAN_URI=unix:///run/podman/podman.sock

# Command-line flag
--provider.podman.uri=unix:///run/podman/podman.sock

--provider.proxmox-lxc.tls-insecure

Skip TLS certificate verification for Proxmox VE API

boolean
Default: false
Since v1.12.0

# sablier.yaml
provider:
  proxmox-lxc:
    tls-insecure: false
# Environment variable
SABLIER_PROVIDER_PROXMOX_LXC_TLS_INSECURE=false

# Command-line flag
--provider.proxmox-lxc.tls-insecure=false

--provider.proxmox-lxc.token-id

Proxmox VE API token ID (e.g. root@pam!sablier)

string
Since v1.12.0

# sablier.yaml
provider:
  proxmox-lxc:
    token-id: <string>
# Environment variable
SABLIER_PROVIDER_PROXMOX_LXC_TOKEN_ID=<string>

# Command-line flag
--provider.proxmox-lxc.token-id=<string>

--provider.proxmox-lxc.token-secret

Proxmox VE API token secret

string
Since v1.12.0

# sablier.yaml
provider:
  proxmox-lxc:
    token-secret: <string>
# Environment variable
SABLIER_PROVIDER_PROXMOX_LXC_TOKEN_SECRET=<string>

# Command-line flag
--provider.proxmox-lxc.token-secret=<string>

--provider.proxmox-lxc.url

Proxmox VE API URL (e.g. https://proxmox:8006/api2/json)

string
Since v1.12.0

# sablier.yaml
provider:
  proxmox-lxc:
    url: <string>
# Environment variable
SABLIER_PROVIDER_PROXMOX_LXC_URL=<string>

# Command-line flag
--provider.proxmox-lxc.url=<string>

--provider.reject-unlabeled-requests

Reject direct named requests for instances without sablier.enable=true

boolean
Default: false
Since v1.13.0

# sablier.yaml
provider:
  reject-unlabeled-requests: false
# Environment variable
SABLIER_PROVIDER_REJECT_UNLABELED_REQUESTS=false

# Command-line flag
--provider.reject-unlabeled-requests=false

--provider.verify-enabled-on-expiration

Verify sablier.enable=true before stopping expired instances

boolean
Default: false
Since v1.13.0

# sablier.yaml
provider:
  verify-enabled-on-expiration: false
# Environment variable
SABLIER_PROVIDER_VERIFY_ENABLED_ON_EXPIRATION=false

# Command-line flag
--provider.verify-enabled-on-expiration=false

Server

OptionDescription
--server.base-pathThe base path for the API
--server.metrics.enabledEnable the Prometheus /metrics endpoint
--server.portThe server port to use

--server.base-path

The base path for the API

string
Default: /
Since v1.0.0

# sablier.yaml
server:
  base-path: /
# Environment variable
SABLIER_SERVER_BASE_PATH=/

# Command-line flag
--server.base-path=/

--server.metrics.enabled

Enable the Prometheus /metrics endpoint

boolean
Default: false
Since v1.12.0

# sablier.yaml
server:
  metrics:
    enabled: false
# Environment variable
SABLIER_SERVER_METRICS_ENABLED=false

# Command-line flag
--server.metrics.enabled=false

--server.port

The server port to use

integer
Default: 10000
Since v1.0.0

# sablier.yaml
server:
  port: 10000
# Environment variable
SABLIER_SERVER_PORT=10000

# Command-line flag
--server.port=10000

Sessions

OptionDescription
--sessions.default-durationThe default session duration
--sessions.expiration-intervalThe expiration checking interval.

--sessions.default-duration

The default session duration

duration
Default: 5m0s
Since v1.0.0

# sablier.yaml
sessions:
  default-duration: 5m0s
# Environment variable
SABLIER_SESSIONS_DEFAULT_DURATION=5m0s

# Command-line flag
--sessions.default-duration=5m0s

--sessions.expiration-interval

The expiration checking interval. Higher duration gives less stress on CPU. If you only use sessions of 1h, setting this to 5m is a good trade-off.

duration
Default: 20s
Since v1.0.0

# sablier.yaml
sessions:
  expiration-interval: 20s
# Environment variable
SABLIER_SESSIONS_EXPIRATION_INTERVAL=20s

# Command-line flag
--sessions.expiration-interval=20s

Storage

OptionDescription
--storage.fileFile path to save the state

--storage.file

File path to save the state

string
Since v1.0.0

# sablier.yaml
storage:
  file: <string>
# Environment variable
SABLIER_STORAGE_FILE=<string>

# Command-line flag
--storage.file=<string>

Strategy

OptionDescription
--strategy.blocking.default-refresh-frequencyDefault refresh frequency at which the instances status are checked for blocking strategy
--strategy.blocking.default-timeoutDefault timeout used for blocking strategy
--strategy.dynamic.custom-themes-pathCustom themes folder, will load all .html files recursively
--strategy.dynamic.default-refresh-frequencyDefault refresh frequency in the HTML page for dynamic strategy
--strategy.dynamic.default-themeDefault theme used for dynamic strategy
--strategy.dynamic.show-details-by-defaultShow the loading instances details by default

--strategy.blocking.default-refresh-frequency

Default refresh frequency at which the instances status are checked for blocking strategy

duration
Default: 5s
Since v1.9.0

# sablier.yaml
strategy:
  blocking:
    default-refresh-frequency: 5s
# Environment variable
SABLIER_STRATEGY_BLOCKING_DEFAULT_REFRESH_FREQUENCY=5s

# Command-line flag
--strategy.blocking.default-refresh-frequency=5s

--strategy.blocking.default-timeout

Default timeout used for blocking strategy

duration
Default: 1m0s
Since v1.0.0

# sablier.yaml
strategy:
  blocking:
    default-timeout: 1m0s
# Environment variable
SABLIER_STRATEGY_BLOCKING_DEFAULT_TIMEOUT=1m0s

# Command-line flag
--strategy.blocking.default-timeout=1m0s

--strategy.dynamic.custom-themes-path

Custom themes folder, will load all .html files recursively

string
Since v1.0.0

# sablier.yaml
strategy:
  dynamic:
    custom-themes-path: <string>
# Environment variable
SABLIER_STRATEGY_DYNAMIC_CUSTOM_THEMES_PATH=<string>

# Command-line flag
--strategy.dynamic.custom-themes-path=<string>

--strategy.dynamic.default-refresh-frequency

Default refresh frequency in the HTML page for dynamic strategy

duration
Default: 5s
Since v1.0.0

# sablier.yaml
strategy:
  dynamic:
    default-refresh-frequency: 5s
# Environment variable
SABLIER_STRATEGY_DYNAMIC_DEFAULT_REFRESH_FREQUENCY=5s

# Command-line flag
--strategy.dynamic.default-refresh-frequency=5s

--strategy.dynamic.default-theme

Default theme used for dynamic strategy

string
Default: hacker-terminal
Since v1.0.0

# sablier.yaml
strategy:
  dynamic:
    default-theme: hacker-terminal
# Environment variable
SABLIER_STRATEGY_DYNAMIC_DEFAULT_THEME=hacker-terminal

# Command-line flag
--strategy.dynamic.default-theme=hacker-terminal

--strategy.dynamic.show-details-by-default

Show the loading instances details by default

boolean
Default: true
Since v1.0.0

# sablier.yaml
strategy:
  dynamic:
    show-details-by-default: true
# Environment variable
SABLIER_STRATEGY_DYNAMIC_SHOW_DETAILS_BY_DEFAULT=true

# Command-line flag
--strategy.dynamic.show-details-by-default=true

Tracing

OptionDescription
--tracing.enabledEnable OpenTelemetry distributed tracing
--tracing.endpointOTLP collector base URL (used when tracing.exporter-type=otlphttp)
--tracing.exporter-typeTrace exporter backend: otlphttp or stdout
--tracing.sampling-rateFraction of traces to sample (0.0-1.0)
--tracing.service-nameService name reported to the tracing backend

--tracing.enabled

Enable OpenTelemetry distributed tracing

boolean
Default: false
Since v1.13.0

# sablier.yaml
tracing:
  enabled: false
# Environment variable
SABLIER_TRACING_ENABLED=false

# Command-line flag
--tracing.enabled=false

--tracing.endpoint

OTLP collector base URL (used when tracing.exporter-type=otlphttp)

string
Default: http://localhost:4318
Since v1.13.0

# sablier.yaml
tracing:
  endpoint: http://localhost:4318
# Environment variable
SABLIER_TRACING_ENDPOINT=http://localhost:4318

# Command-line flag
--tracing.endpoint=http://localhost:4318

--tracing.exporter-type

Trace exporter backend: otlphttp or stdout

string
Default: otlphttp
Since v1.13.0

Accepted values:

  • otlphttp
  • stdout
# sablier.yaml
tracing:
  exporter-type: otlphttp
# Environment variable
SABLIER_TRACING_EXPORTER_TYPE=otlphttp

# Command-line flag
--tracing.exporter-type=otlphttp

--tracing.sampling-rate

Fraction of traces to sample (0.0-1.0)

number
Default: 1
Since v1.13.0

# sablier.yaml
tracing:
  sampling-rate: 1
# Environment variable
SABLIER_TRACING_SAMPLING_RATE=1

# Command-line flag
--tracing.sampling-rate=1

--tracing.service-name

Service name reported to the tracing backend

string
Default: sablier
Since v1.13.0

# sablier.yaml
tracing:
  service-name: sablier
# Environment variable
SABLIER_TRACING_SERVICE_NAME=sablier

# Command-line flag
--tracing.service-name=sablier
Label reference