Command-line tool for the TLTV Federation Protocol.
Single static binary, zero dependencies.
curl -sSL https://raw.githubusercontent.com/tltv-org/cli/main/install.sh | sh
Or with Docker:
docker run --rm -v tltv-keys:/data -p 8000:8000 tltv bridge \
--stream http://provider.example.com/channels.m3u
Or from source (go install github.com/tltv-org/cli@latest). See docs/install.md for all options.
# Generate a channel identity
tltv keygen
# Mine a vanity channel ID
tltv vanity cool
# Sign a metadata document
tltv template metadata > meta.json
tltv sign -k <channel-id>.key --auto-seq < meta.json > signed.json
# Bridge external streams as TLTV channels
tltv bridge --stream http://provider.com/channels.m3u --guide http://provider.com/guide.xml
# Rebroadcast another TLTV channel under your own identity
tltv bridge --stream "tltv://TVAlice@alice.tv" -k my.key --name "My Channel"
# Relay channels from another node
tltv relay --node origin.example.com:443
# Mirror an origin (same key, auto-failover)
tltv mirror --source "tltv://TVabc@primary.tv" --key channel.key --hostname mirror.tv --buffer 2h
# Generate a test signal
tltv server test --name "My Channel" -k channel.key
# Watch a channel
tltv viewer demo.timelooptv.org
| Command |
Description |
info <target> |
Show all info about a target (--watch for auto-refresh) |
channel <target> |
Fetch and verify channel metadata |
stream <target> |
Check stream status and manifest info (--url for bare URL) |
guide <target> |
Fetch and verify channel guide (--xmltv for XML output) |
node <host> |
Query node identity from /.well-known/tltv |
peers <host> |
List peers from a node |
| Command |
Description |
resolve <uri> |
End-to-end URI resolution with migration chain following |
crawl <host> |
BFS-crawl the gossip network (--depth for max depth) |
| Command |
Description |
server test |
Test signal generator (--channels N, --variants 1080p,720p) (docs) |
bridge |
Bridge origin server (docs) |
relay |
Caching relay with signature verification (docs) |
mirror |
Mirror origin — same-key replication with auto-promotion (docs) |
router |
SNI routing reverse proxy with built-in ACME TLS (docs) |
Private origins: Run a server or bridge without --hostname to create a
private origin. Without a hostname, signed metadata contains no origins field,
so relays cannot discover the server's address.
Private embedded viewer: On a private server test origin with --viewer,
open /?token=.... The embedded viewer routes are token-gated and /api/info
does not echo the secret back to the browser.
| Command |
Description |
viewer <target> |
Web viewer with HLS.js player (--viewer production, --debug-viewer diagnostic) |
receiver <target> |
Headless HLS consumer (--monitor, --record, --pipe, --quality) |
| Command |
Description |
keygen |
Generate Ed25519 keypair and channel ID |
vanity <pattern> |
Mine channel IDs matching a pattern (multi-threaded) |
inspect <id> |
Decode and validate a channel ID |
| Command |
Description |
sign |
Sign a JSON document with Ed25519 (-k, --auto-seq) |
verify |
Verify a signed document's signature and protocol version |
template |
Output a JSON template (metadata, guide, migration) |
migrate |
Create a signed key migration document |
| Command |
Description |
parse <uri> |
Parse a tltv:// URI into components |
format <id> |
Build a tltv:// URI from channel ID and hints |
| Command |
Description |
loadtest <target> |
Multi-receiver load simulator |
version |
Version, protocol version, platform info |
update |
Self-update to latest GitHub release |
completion |
Shell completions and flag metadata (--install, --flags) |
| Flag |
Description |
--json / -j |
Machine-readable JSON output |
--no-color / -C |
Disable colored output (also respects NO_COLOR) |
--insecure / -I |
HTTP transport, skip TLS verification |
--local / -L |
Allow local/private address hints in resolve and crawl |
Global flags work before or after the subcommand: tltv --json channel ... and tltv channel --json ... are equivalent.
Validated against all 7 test vector suites from the protocol specification (C1–C7: identity encoding, signing, documents, URIs, guides, invalid inputs, migration). 661 tests. Run make test to verify.
MIT — see LICENSE.