CLI, environment & config reference

Complete generated mapping of Teldrive config keys to command-line flags and TELDRIVE_ environment variables.

Generated from the server configuration structs. Precedence: defaults < config file < environment < explicit CLI flags.

Name mapping example: http.address → TELDRIVE_HTTP_ADDRESS → --http-address. Slices use comma-separated values; encryption maps use version:key entries.

Defaults are runtime values, not production recommendations.

Cache

`cache.memory.size`

Global Ristretto memory cache size (e.g., 5MB, 10MB)

Default: 5MB
CLI flag: --cache-memory-size
Environment: TELDRIVE_CACHE_MEMORY_SIZE

Database

`database.application-name`

PostgreSQL application name

Default: teldrive-v2
CLI flag: --database-application-name
Environment: TELDRIVE_DATABASE_APPLICATION_NAME

`database.auto-migrate-legacy`

Automatically migrate a detected TelDrive v1 database during startup

Default: true
CLI flag: --database-auto-migrate-legacy
Environment: TELDRIVE_DATABASE_AUTO_MIGRATE_LEGACY

`database.connect-timeout`

PostgreSQL connection timeout

Default: 10s
CLI flag: --database-connect-timeout
Environment: TELDRIVE_DATABASE_CONNECT_TIMEOUT

`database.health-check-interval`

PostgreSQL pool health-check interval

Default: 30s
CLI flag: --database-health-check-interval
Environment: TELDRIVE_DATABASE_HEALTH_CHECK_INTERVAL

`database.max-connection-idle`

Maximum idle time for a PostgreSQL connection

Default: 5m0s
CLI flag: --database-max-connection-idle
Environment: TELDRIVE_DATABASE_MAX_CONNECTION_IDLE

`database.max-connection-life`

Maximum lifetime for a PostgreSQL connection

Default: 30m0s
CLI flag: --database-max-connection-life
Environment: TELDRIVE_DATABASE_MAX_CONNECTION_LIFE

`database.max-connections`

Maximum PostgreSQL connections

Default: 25
CLI flag: --database-max-connections
Environment: TELDRIVE_DATABASE_MAX_CONNECTIONS

`database.min-connections`

Minimum PostgreSQL connections

Default: 2
CLI flag: --database-min-connections
Environment: TELDRIVE_DATABASE_MIN_CONNECTIONS

`database.schema`

PostgreSQL schema for all TelDrive and River tables

Default: teldrive
CLI flag: --database-schema
Environment: TELDRIVE_DATABASE_SCHEMA

`database.url`

PostgreSQL connection URL

Default: Not set
CLI flag: --database-url
Environment: TELDRIVE_DATABASE_URL

Encryption

`encryption.active-key-version`

Active server-managed encryption key version for new uploads

Default: 0
CLI flag: --encryption-active-key-version
Environment: TELDRIVE_ENCRYPTION_ACTIVE_KEY_VERSION

`encryption.keys`

Encryption keys as comma-separated version:key entries

Default: Not set
CLI flag: --encryption-keys
Environment: TELDRIVE_ENCRYPTION_KEYS

Events

`events.batch-size`

Maximum events read from PostgreSQL per SSE batch

Default: 100
CLI flag: --events-batch-size
Environment: TELDRIVE_EVENTS_BATCH_SIZE

`events.cleanup-interval`

Expired event stream ticket cleanup interval

Default: 1h0m0s
CLI flag: --events-cleanup-interval
Environment: TELDRIVE_EVENTS_CLEANUP_INTERVAL

`events.connect-timeout`

PostgreSQL event listener connection timeout

Default: 10s
CLI flag: --events-connect-timeout
Environment: TELDRIVE_EVENTS_CONNECT_TIMEOUT

`events.heartbeat`

SSE heartbeat interval

Default: 20s
CLI flag: --events-heartbeat
Environment: TELDRIVE_EVENTS_HEARTBEAT

`events.max-connections-per-user`

Maximum concurrent SSE connections per user on one API instance

Default: 5
CLI flag: --events-max-connections-per-user
Environment: TELDRIVE_EVENTS_MAX_CONNECTIONS_PER_USER

`events.ping-interval`

PostgreSQL event listener health-check interval

Default: 5s
CLI flag: --events-ping-interval
Environment: TELDRIVE_EVENTS_PING_INTERVAL

`events.reconnect-max`

Maximum PostgreSQL listener reconnect delay

Default: 30s
CLI flag: --events-reconnect-max
Environment: TELDRIVE_EVENTS_RECONNECT_MAX

`events.reconnect-min`

Minimum PostgreSQL listener reconnect delay

Default: 100ms
CLI flag: --events-reconnect-min
Environment: TELDRIVE_EVENTS_RECONNECT_MIN

`events.ticket-ttl`

Lifetime of browser event stream tickets

Default: 2m0s
CLI flag: --events-ticket-ttl
Environment: TELDRIVE_EVENTS_TICKET_TTL

`events.write-timeout`

Maximum duration for one SSE write and flush

Default: 10s
CLI flag: --events-write-timeout
Environment: TELDRIVE_EVENTS_WRITE_TIMEOUT

HTTP

`http.address`

HTTP listen address

Default: 127.0.0.1:8080
CLI flag: --http-address
Environment: TELDRIVE_HTTP_ADDRESS

`http.idle-timeout`

HTTP keep-alive idle timeout

Default: 2m0s
CLI flag: --http-idle-timeout
Environment: TELDRIVE_HTTP_IDLE_TIMEOUT

`http.read-header-timeout`

Maximum time to read request headers

Default: 10s
CLI flag: --http-read-header-timeout
Environment: TELDRIVE_HTTP_READ_HEADER_TIMEOUT

`http.read-timeout`

Maximum time to read an entire request; zero disables it for streaming uploads

Default: 1h0m0s
CLI flag: --http-read-timeout
Environment: TELDRIVE_HTTP_READ_TIMEOUT

`http.shutdown-timeout`

Graceful shutdown timeout

Default: 10s
CLI flag: --http-shutdown-timeout
Environment: TELDRIVE_HTTP_SHUTDOWN_TIMEOUT

`http.trusted-proxies`

Proxy IP addresses or CIDRs trusted to set forwarding headers

Default: Not set
CLI flag: --http-trusted-proxies
Environment: TELDRIVE_HTTP_TRUSTED_PROXIES

`http.write-timeout`

Maximum response write duration; zero disables it for streaming

Default: 1h0m0s
CLI flag: --http-write-timeout
Environment: TELDRIVE_HTTP_WRITE_TIMEOUT

Jobs

`jobs.run-workers`

Run River background job workers in this process

Default: true
CLI flag: --jobs-run-workers
Environment: TELDRIVE_JOBS_RUN_WORKERS

Logging

`logging.log-format`

Log format: json or text

Default: text
CLI flag: --logging-log-format
Environment: TELDRIVE_LOGGING_LOG_FORMAT

`logging.log-level`

Log level: debug, info, warn, or error

Default: info
CLI flag: --logging-log-level
Environment: TELDRIVE_LOGGING_LOG_LEVEL

Security

`security.access-token-ttl`

Access-token lifetime

Default: 15m0s
CLI flag: --security-access-token-ttl
Environment: TELDRIVE_SECURITY_ACCESS_TOKEN_TTL

`security.allowed-users`

Allowed Telegram usernames; empty permits every user

Default: Not set
CLI flag: --security-allowed-users
Environment: TELDRIVE_SECURITY_ALLOWED_USERS

`security.data-key`

Key used to encrypt stored Telegram credentials

Default: Not set
CLI flag: --security-data-key
Environment: TELDRIVE_SECURITY_DATA_KEY

`security.issuer`

JWT issuer

Default: teldrive-v2
CLI flag: --security-issuer
Environment: TELDRIVE_SECURITY_ISSUER

`security.login-flow-ttl`

Telegram login-flow lifetime

Default: 10m0s
CLI flag: --security-login-flow-ttl
Environment: TELDRIVE_SECURITY_LOGIN_FLOW_TTL

`security.refresh-token-ttl`

Refresh-token lifetime

Default: 720h0m0s
CLI flag: --security-refresh-token-ttl
Environment: TELDRIVE_SECURITY_REFRESH_TOKEN_TTL

`security.signing-key`

JWT signing key

Default: Not set
CLI flag: --security-signing-key
Environment: TELDRIVE_SECURITY_SIGNING_KEY

`telegram.app-hash`

Telegram application hash

Default: 8da85b0d5bfe62527e5b244c209159c3
CLI flag: --telegram-app-hash
Environment: TELDRIVE_TELEGRAM_APP_HASH

`telegram.app-id`

Telegram application ID

Default: 2496
CLI flag: --telegram-app-id
Environment: TELDRIVE_TELEGRAM_APP_ID

`telegram.app-version`

Telegram client application version

Default: 6.1.4 K
CLI flag: --telegram-app-version
Environment: TELDRIVE_TELEGRAM_APP_VERSION

`telegram.auto-channel-create`

Create storage channels automatically

Default: true
CLI flag: --telegram-auto-channel-create
Environment: TELDRIVE_TELEGRAM_AUTO_CHANNEL_CREATE

`telegram.backend`

Telegram backend: remote or filesystem

Default: remote
CLI flag: --telegram-backend
Environment: TELDRIVE_TELEGRAM_BACKEND

`telegram.bot-rotation-backend`

Bot rotation backend: memory for single-instance speed or database for cluster-wide coordination

Default: memory
CLI flag: --telegram-bot-rotation-backend
Environment: TELDRIVE_TELEGRAM_BOT_ROTATION_BACKEND

`telegram.channel-name-prefix`

Prefix for automatically created channels

Default: teldrive
CLI flag: --telegram-channel-name-prefix
Environment: TELDRIVE_TELEGRAM_CHANNEL_NAME_PREFIX

`telegram.channel-part-limit`

Maximum parts stored in one Telegram channel

Default: 500000
CLI flag: --telegram-channel-part-limit
Environment: TELDRIVE_TELEGRAM_CHANNEL_PART_LIMIT

`telegram.client-logging`

Enable verbose gotd Telegram client logs through the application logger

Default: false
CLI flag: --telegram-client-logging
Environment: TELDRIVE_TELEGRAM_CLIENT_LOGGING

`telegram.device-model`

Telegram client device model

Default: Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:109.0) Gecko/20100101 Firefox/116.0
CLI flag: --telegram-device-model
Environment: TELDRIVE_TELEGRAM_DEVICE_MODEL

`telegram.dial-timeout`

Telegram connection timeout

Default: 10s
CLI flag: --telegram-dial-timeout
Environment: TELDRIVE_TELEGRAM_DIAL_TIMEOUT

`telegram.download-bots`

Maximum enabled bots used for download rotation; zero uses the authenticated user

Default: 0
CLI flag: --telegram-download-bots
Environment: TELDRIVE_TELEGRAM_DOWNLOAD_BOTS

`telegram.download-client-pool`

Keep authenticated Telegram download clients warm between HTTP requests

Default: false
CLI flag: --telegram-download-client-pool
Environment: TELDRIVE_TELEGRAM_DOWNLOAD_CLIENT_POOL

`telegram.download-read-buffers`

Number of prefetched Telegram download chunks buffered in memory per stream

Default: 32
CLI flag: --telegram-download-read-buffers
Environment: TELDRIVE_TELEGRAM_DOWNLOAD_READ_BUFFERS

`telegram.download-read-parallel`

Concurrent Telegram chunk fetches per download stream

Default: 4
CLI flag: --telegram-download-read-parallel
Environment: TELDRIVE_TELEGRAM_DOWNLOAD_READ_PARALLEL

`telegram.language-code`

Telegram client language code

Default: en
CLI flag: --telegram-language-code
Environment: TELDRIVE_TELEGRAM_LANGUAGE_CODE

`telegram.language-pack`

Telegram client language pack

Default: webk
CLI flag: --telegram-language-pack
Environment: TELDRIVE_TELEGRAM_LANGUAGE_PACK

`telegram.local-root`

Filesystem root used by the local Telegram emulator

Default: ./var/local-telegram
CLI flag: --telegram-local-root
Environment: TELDRIVE_TELEGRAM_LOCAL_ROOT

`telegram.max-retries`

Maximum Telegram transport retry attempts

Default: 10
CLI flag: --telegram-max-retries
Environment: TELDRIVE_TELEGRAM_MAX_RETRIES

`telegram.mtproxy.address`

MTProto proxy address in host:port form

Default: Not set
CLI flag: --telegram-mtproxy-address
Environment: TELDRIVE_TELEGRAM_MTPROXY_ADDRESS

`telegram.mtproxy.secret`

MTProto proxy secret in hexadecimal form

Default: Not set
CLI flag: --telegram-mtproxy-secret
Environment: TELDRIVE_TELEGRAM_MTPROXY_SECRET

`telegram.proxy`

HTTP, HTTPS, or SOCKS5 proxy URL

Default: Not set
CLI flag: --telegram-proxy
Environment: TELDRIVE_TELEGRAM_PROXY

`telegram.randomize-part-names`

Randomize Telegram document names

Default: true
CLI flag: --telegram-randomize-part-names
Environment: TELDRIVE_TELEGRAM_RANDOMIZE_PART_NAMES

`telegram.rate-burst`

Telegram API request burst allowance

Default: 10
CLI flag: --telegram-rate-burst
Environment: TELDRIVE_TELEGRAM_RATE_BURST

`telegram.rate-interval`

Minimum interval between Telegram API requests

Default: 50ms
CLI flag: --telegram-rate-interval
Environment: TELDRIVE_TELEGRAM_RATE_INTERVAL

`telegram.rate-limit`

Enable Telegram API request rate limiting

Default: true
CLI flag: --telegram-rate-limit
Environment: TELDRIVE_TELEGRAM_RATE_LIMIT

`telegram.reconnect-timeout`

Maximum Telegram reconnect backoff duration

Default: 5m0s
CLI flag: --telegram-reconnect-timeout
Environment: TELDRIVE_TELEGRAM_RECONNECT_TIMEOUT

`telegram.system-language-code`

Telegram client system language code

Default: en-US
CLI flag: --telegram-system-language-code
Environment: TELDRIVE_TELEGRAM_SYSTEM_LANGUAGE_CODE

`telegram.system-version`

Telegram client system version

Default: Win32
CLI flag: --telegram-system-version
Environment: TELDRIVE_TELEGRAM_SYSTEM_VERSION

`telegram.upload-threads`

Concurrent Telegram upload workers

Default: 8
CLI flag: --telegram-upload-threads
Environment: TELDRIVE_TELEGRAM_UPLOAD_THREADS

Uploads

`uploads.hashing-enabled`

Compute and store BLAKE3 hashes for uploaded files

Default: true
CLI flag: --uploads-hashing-enabled
Environment: TELDRIVE_UPLOADS_HASHING_ENABLED

`uploads.local-import-roots`

Absolute server directories allowed as local background-upload sources; empty disables local imports

Default: Not set
CLI flag: --uploads-local-import-roots
Environment: TELDRIVE_UPLOADS_LOCAL_IMPORT_ROOTS

`uploads.session-ttl`

Lifetime of resumable upload sessions

Default: 168h0m0s
CLI flag: --uploads-session-ttl
Environment: TELDRIVE_UPLOADS_SESSION_TTL

CLI, environment & config reference

cache.memory.size

database.application-name

database.auto-migrate-legacy

database.connect-timeout

database.health-check-interval

database.max-connection-idle

database.max-connection-life

database.max-connections

database.min-connections

database.schema

database.url

encryption.active-key-version

encryption.keys

events.batch-size

events.cleanup-interval

events.connect-timeout

events.heartbeat

events.max-connections-per-user

events.ping-interval

events.reconnect-max

events.reconnect-min

events.ticket-ttl

events.write-timeout

http.address

http.idle-timeout

http.read-header-timeout

http.read-timeout

http.shutdown-timeout

http.trusted-proxies

http.write-timeout

jobs.run-workers

logging.log-format

logging.log-level

security.access-token-ttl

security.allowed-users

security.data-key

security.issuer

security.login-flow-ttl

security.refresh-token-ttl

security.signing-key

telegram.app-hash

telegram.app-id

telegram.app-version

telegram.auto-channel-create

telegram.backend

telegram.bot-rotation-backend

telegram.channel-name-prefix

telegram.channel-part-limit

telegram.client-logging

telegram.device-model

telegram.dial-timeout

telegram.download-bots

telegram.download-client-pool

telegram.download-read-buffers

telegram.download-read-parallel

telegram.language-code

telegram.language-pack

telegram.local-root

telegram.max-retries

telegram.mtproxy.address

telegram.mtproxy.secret

telegram.proxy

telegram.randomize-part-names

telegram.rate-burst

telegram.rate-interval

telegram.rate-limit

telegram.reconnect-timeout

telegram.system-language-code

telegram.system-version

telegram.upload-threads

uploads.hashing-enabled

uploads.local-import-roots

uploads.session-ttl

On this page