id       = "tor"
name     = "Tor"
homepage = "https://www.torproject.org"
description = "The second-generation onion router."
executables   = ["tor"]

[dotfiles]

# torrc(5) (https://manpages.debian.org/unstable/tor/torrc.5.en.html) says
# the default configuration is /etc/tor/torrc, falling back to $HOME/.torrc
# when the system file is absent. The latter is the user-authored file; system
# configuration and Tor's DataDirectory are outside this entry.
paths = ["~/.torrc"]

exclude = []
secret = []

side_effect = false

# torrc can contain a HashedControlPassword, which is an authentication
# credential even though it is stored as a hash.
[[dotfiles.secret_paths]]
file  = "~/.torrc"
match = { prefix = ["HashedControlPassword"] }

[commands]
format = 1
label = "Run or check Tor"
description = "Start tor with a chosen torrc and SOCKS port, or only verify the configuration. Hashing passwords, key listing and Windows service 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 = "manual"
kind = "manual"
url = "https://gitlab.torproject.org/tpo/core/tor/-/raw/main/doc/man/tor.1.txt"
revision = "2026-10-27"
evidence = """
-f, --torrc-file FILE
    Specify a new configuration file to contain further Tor configuration options
--allow-missing-torrc
    Allow the configuration file specified by -f to be missing
--ignore-missing-torrc
    Specify that Tor should treat a missing torrc file as though it were empty.
--verify-config
    Verify whether the configuration file is valid.
--dump-config short|full
    Write a list of Tor's configured options to standard output.
--list-torrc-options
    List all valid options.
format --OptionName OptionValue: --SocksPort 9999
"""

[[commands.field]]
id = "torrc"
label = "torrc file"
type = "path"
path = { kind = "file", role = "input" }
option = ["-f", "--torrc-file"]
sources = ["manual"]

[[commands.field]]
id = "socks_port"
label = "SOCKS port"
type = "integer"
option = ["--SocksPort"]
sources = ["manual"]

[[commands.field]]
id = "verify_config"
label = "Verify configuration only"
type = "boolean"
option = ["--verify-config"]
sources = ["manual"]

[[commands.field]]
id = "dump_config"
label = "Dump configuration"
type = "enum"
option = ["--dump-config"]
choices = [{ value = "short", label = "Only non-default options" }, { value = "full", label = "All options" }]
sources = ["manual"]

[[commands.field]]
id = "list_options"
label = "List valid options"
type = "boolean"
option = ["--list-torrc-options"]
sources = ["manual"]

[[commands.field]]
id = "allow_missing"
label = "Allow missing torrc"
type = "boolean"
option = ["--allow-missing-torrc"]
sources = ["manual"]

[[commands.task]]
id = "verify"
label = "Verify a torrc"
fields = ["torrc", "verify_config"]
required = ["torrc", "verify_config"]
set = { verify_config = [true] }

[[commands.task]]
id = "run"
label = "Start with a torrc"
fields = ["torrc", "socks_port"]
required = ["torrc"]

[[commands.group]]
id = "basic"
label = "Basic"
fields = ["torrc", "socks_port", "verify_config"]

[[commands.group]]
id = "advanced"
label = "Advanced"
fields = ["dump_config", "list_options", "allow_missing"]