id       = "ttl"
name     = "ttl"
homepage = "https://github.com/lance0/ttl"
description = "Fast, modern traceroute with real-time TUI, per-hop stats, ASN/geo lookup, ECMP detection, and MPLS label parsing. A better mtr."
executables   = ["ttl"]
platforms = ["macos", "linux"]

[dotfiles]

# ttl's own documentation says Linux persists settings at ~/.config/ttl/config.toml.
# On macOS it moved from ~/Library/Preferences/ttl/config.toml to
# ~/Library/Application Support/ttl/config.toml in v0.12.1. The old path is
# retained for users upgrading from earlier releases.
# https://github.com/lance0/ttl/blob/master/README.md
paths = [
  "~/.config/ttl/config.toml",
  "[appData]/ttl/config.toml",
  "[preferences]/ttl/config.toml",
]
exclude = []
secret = []

# The docs confirm a PeeringDB API key can be saved in this TOML, but do not
# specify its serialized key path; leave secret_paths unset rather than invent
# a matcher. Consumers should still scan the config content for credentials.

[commands]
format = 1
label = "Trace route"
description = "Trace the path to one or more hosts with ttl. Output modes other than the report, replay, diff, Prometheus and enrichment options are left out."
quality = "ai-draft"
parser = { end_of_options = "--", interleave = "permute", long_equals = true, short_attached = true, short_bundles = false }

[[commands.source]]
id = "help"
kind = "manual"
url = "https://github.com/lance0/ttl/blob/master/docs/FEATURES.md#cli-reference"
revision = "2026-10-27"
evidence = """
  -c, --count <N>            Probe rounds; 0 = run until quit (default: 0)
  -i, --interval <S>         Seconds between rounds (default: 1.0)
  -m, --max-ttl <N>          Maximum TTL, 1-64 (default: 30)
  -p, --protocol <P>         auto, icmp, udp, tcp (default: auto)
      --flows <N>            Flows for ECMP detection, 1-16 (default: 1; needs UDP or TCP)
  -4, --ipv4                 Force IPv4
  -6, --ipv6                 Force IPv6
      --no-dns               Skip reverse DNS
      --no-tui               Plain text output, one line per hop each round
      --report               Text report at the end of the run (requires -c)
Usage: ttl [OPTIONS] [TARGETS]...
"""

[[commands.field]]
id = "targets"
label = "Targets"
description = "Hostnames or IP addresses. Empty opens an interactive session."
type = "string"
position = 0
multiple = true
sources = ["help"]

[[commands.field]]
id = "count"
label = "Rounds"
description = "0 runs until quit."
type = "integer"
option = ["--count", "-c"]
sources = ["help"]

[[commands.field]]
id = "interval"
label = "Interval (seconds)"
type = "number"
option = ["--interval", "-i"]
sources = ["help"]

[[commands.field]]
id = "max_ttl"
label = "Maximum TTL"
type = "integer"
option = ["--max-ttl", "-m"]
sources = ["help"]

[[commands.field]]
id = "protocol"
label = "Protocol"
type = "enum"
option = ["--protocol", "-p"]
choices = [{ value = "auto", label = "Auto" }, { value = "icmp", label = "ICMP" }, { value = "udp", label = "UDP" }, { value = "tcp", label = "TCP" }]
sources = ["help"]

[[commands.field]]
id = "flows"
label = "ECMP flows"
description = "Needs UDP or TCP."
type = "integer"
option = ["--flows"]
sources = ["help"]

[[commands.field]]
id = "ipv4"
label = "Force IPv4"
type = "boolean"
option = ["--ipv4", "-4"]
sources = ["help"]

[[commands.field]]
id = "ipv6"
label = "Force IPv6"
type = "boolean"
option = ["--ipv6", "-6"]
sources = ["help"]

[[commands.field]]
id = "no_dns"
label = "Skip reverse DNS"
type = "boolean"
option = ["--no-dns"]
sources = ["help"]

[[commands.field]]
id = "no_tui"
label = "Plain text output"
type = "boolean"
option = ["--no-tui"]
sources = ["help"]

[[commands.field]]
id = "report"
label = "Text report at end"
description = "Requires a round count."
type = "boolean"
option = ["--report"]
sources = ["help"]

[[commands.task]]
id = "live"
label = "Live trace"
fields = ["targets", "protocol", "ipv4", "ipv6", "no_dns"]
required = ["targets"]

[[commands.task]]
id = "report"
label = "100-round report"
set = { count = [100], report = [true] }
lock = ["report"]
fields = ["targets", "count", "protocol", "interval", "no_dns"]
required = ["targets"]

[[commands.group]]
id = "basic"
label = "Basic"
fields = ["targets", "count", "protocol", "interval", "report"]

[[commands.group]]
id = "advanced"
label = "Advanced"
fields = ["max_ttl", "flows", "ipv4", "ipv6", "no_dns", "no_tui"]