Skip to main content

​
Run modes

tuliprox has two distinct run modes:
ModeFlagDescription
CLI mode(no flag)Process playlists once and exit. Useful for scripting and cron-based updates.
Server mode-s / --serverStart the HTTP API, background scheduler, Web UI, and live proxy. This is the normal production mode.

​
CLI mode

In CLI mode, tuliprox reads your sources, processes the playlist, writes the output files, and exits. Use this when you want to generate static M3U files to serve with your own web server (Nginx, Apache, Caddy, etc.): 
tuliprox -c config/config.yml -i config/source.yml
You can limit processing to a specific target by passing -t: 
tuliprox -c config/config.yml -i config/source.yml -t my-target

​
Server mode

In server mode, tuliprox starts a long-running process that exposes the M3U, Xtream Codes, HDHomeRun, and management APIs, runs the background scheduler, and serves the Web UI: 
tuliprox -s -c config/config.yml -i config/source.yml
This is the mode used in the Docker deployment.

​
CLI arguments

FlagShortDescription
--home <HOME>-HOverride the home directory (see resolution order below)
--config-path <CONFIG_PATH>-pDirectory to search for config files
--config <CONFIG_FILE>-cPath to config.yml
--source <SOURCE_FILE>-iPath to source.yml
--mapping <MAPPING_FILE>-mPath to mapping.yml
--template <TEMPLATE_FILE>-TPath to template.yml
--target <TARGET>-tProcess only the named target (CLI mode)
--api-proxy <API_PROXY>-aPath to api-proxy.yml
--server-sRun in server mode
--log-level <LOG_LEVEL>-lOverride the log level (error, warn, info, debug, trace)
--genpwdGenerate a bcrypt password hash for the Web UI user file
--healthcheckExit 0 if the server is healthy, non-zero otherwise
--scan-libraryTrigger a local media library scan and exit
--force-library-rescanForce a full library rescan, ignoring cached metadata
--dbxOpen the internal database viewer for Xtream data
--dbmOpen the internal database viewer for M3U data
--dbmsOpen the internal database viewer for metadata retry status
--dbeOpen the internal database viewer for EPG data
--dbvOpen the internal database viewer for target-ID mapping
--dbx, --dbm, --dbe, --dbv, and --dbms open interactive database inspection tools for debugging. They are intended for troubleshooting, not normal operation.

​
Home directory resolution

tuliprox resolves its home directory in this priority order:
  1. The --home CLI flag
  2. The TULIPROX_HOME environment variable
  3. The directory containing the tuliprox binary
All relative paths in your configuration files are resolved against the home directory. In Docker deployments, the working directory /app acts as the home directory.

​
Project layout

A typical tuliprox home directory looks like this: 
/app/                    ← home directory (TULIPROX_HOME or binary location)
├── config/
│   ├── config.yml       ← main application config
│   ├── source.yml       ← inputs, sources, and targets
│   ├── api-proxy.yml    ← users and server URL definitions
│   ├── mapping.yml      ← optional channel rename/mapping rules
│   └── template.yml     ← optional reusable template definitions
├── data/                ← processed playlists and working data
│   └── backup/          ← automatic backups of previous playlist state
├── downloads/           ← VOD downloads (if enabled)
├── cache/               ← HTTP response cache and EPG cache
└── web/                 ← Web UI static assets

​
Key configuration files

FilePurpose
config/config.ymlAPI server settings, scheduling, logging, reverse proxy, library config
config/source.ymlInputs (providers), sources, targets, filters, and output formats
config/api-proxy.ymlPer-user credentials, connection limits, server URL announcements
mapping.ymlChannel rename and attribute mapping rules
template.ymlReusable filter/mapping templates (DRY definitions)

​
Utility commands

​
Generate a Web UI password hash

The Web UI user.txt file stores bcrypt-hashed passwords. Generate a hash for a new password: 
tuliprox --genpwd
Enter your desired password when prompted. Paste the resulting hash into user.txt.

​
Healthcheck

tuliprox exposes a healthcheck command suitable for Docker or container orchestration: 
tuliprox --healthcheck
This exits with code 0 if the server is responding and 1 otherwise. Wire it into your docker-compose.yml healthcheck block: 
healthcheck:
  test: ["CMD", "tuliprox", "--healthcheck"]
  interval: 30s
  timeout: 10s
  retries: 3

​
Good first milestone

When setting up tuliprox for the first time, keep the scope small until each step is confirmed working. Adding filtering, mapping, reverse proxy, and metadata features all at once makes it hard to isolate failures.
1

Add one working input

Configure a single input in source.yml — one M3U URL or one set of Xtream Codes credentials. Start tuliprox and confirm it fetches the playlist without errors.
2

Create one target

Define one target with a single output type (start with m3u). Confirm the output file is written to your data/ directory.
3

Confirm playlist output

Open the generated M3U file and check that channels appear as expected. Verify channel count and spot-check group names.
4

Confirm one stream plays

Point VLC or another player at the playlist. Confirm at least one live stream plays from end to end before proceeding.
5

Add advanced features

Only once streaming is confirmed end-to-end, layer in mapping rules, filters, reverse proxy configuration, and metadata enrichment. Adding these one at a time keeps failures easy to diagnose.
Provider-specific issues (wrong credentials, URL format, connection limits) are much easier to diagnose when your tuliprox configuration is minimal. Get a bare pipeline working first.
Once you have a working baseline, explore the rest of the documentation in this order:

Config reference

Full reference for config.yml — API server, scheduling, logging, and reverse proxy settings.

Sources and targets

Define inputs, configure multiple providers, and shape outputs with filters.

API proxy

Configure per-user credentials, connection limits, and published server URLs.

Streaming and proxy

Understand how tuliprox handles live stream proxying, sharing, and failover.

Mapping and templates

Rename channels, rewrite attributes, and define reusable template expressions.

Examples and recipes

Copy-paste recipes for common setups and real-world filtering patterns.

Build docs developers (and LLMs) love

Get started for freeTalk to us