id          = "timewarrior"
name        = "Timewarrior"
homepage    = "https://timewarrior.net"
description = "Timewarrior is a command line time tracker."
executables      = ["timew", "timewarrior"]

[dotfiles]

# The official file-layout documentation says 1.5.0+ uses
# ${XDG_CONFIG_HOME}/timewarrior/timewarrior.cfg (normally ~/.config) and
# that pre-1.5.0 installations retain ~/.timewarrior/timewarrior.cfg.
# https://timewarrior.net/docs/files/
# https://timewarrior.net/reference/timew.1/
paths = [
  "[configHome]/timewarrior/timewarrior.cfg",
  "~/.timewarrior/timewarrior.cfg",
  "[configHome]/timewarrior/extensions/",
  "~/.timewarrior/extensions/",
]

# The XDG data directory and legacy data directory contain tracked intervals,
# not configuration; do not copy them as part of this entry.
exclude = [
  "[xdgData]/timewarrior/data/",
  "~/.timewarrior/data/",
]
secret = []

[commands]
format = 1
label = "Timewarrior"
description = "Track and report time. Start, stop, track past intervals and summarise; hints such as :fill or :week can be typed into the date and range fields."
quality = "ai-draft"
parser = { end_of_options = "--", interleave = "permute", long_equals = false, short_attached = false, short_bundles = false }

[[commands.subcommand]]
path = ["start"]
label = "Start tracking"
description = "Begin tracking now, or at an optional date, with tags."

[[commands.subcommand.source]]
id = "man"
kind = "manual"
url = "https://timewarrior.net/reference/timew-start.1/"
revision = "2026-10-27"
evidence = """
timew start [<date>] [<tag>…​]
Begins tracking using the current time with any specified set of tags.
If a tag contains multiple words, therefore containing spaces, use quotes to surround the whole tag.
"""

[[commands.subcommand.field]]
id = "date"
label = "Start date/time"
description = "Optional, for example 8am."
type = "string"
position = 0

sources = ["man"]

[[commands.subcommand.field]]
id = "tags"
label = "Tags"
description = "Tags to track."
type = "string"
position = 1
multiple = true
sources = ["man"]

[[commands.subcommand.task]]
id = "start_tags"
label = "Start with tags"
fields = ["tags"]
required = ["tags"]

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["date", "tags"]

[[commands.subcommand]]
path = ["stop"]
label = "Stop tracking"
description = "Stop all tracking, or only the given tags."

[[commands.subcommand.source]]
id = "man"
kind = "manual"
url = "https://timewarrior.net/reference/timew-stop.1/"
revision = "2026-10-27"
evidence = """
timew stop [<date>] [<tag>…​]
Stops tracking time.
If tags are specified, then they are no longer tracked.
If no tags are specified, all tracking stops.
"""

[[commands.subcommand.field]]
id = "date"
label = "Stop date/time"
description = "Optional."
type = "string"
position = 0

sources = ["man"]

[[commands.subcommand.field]]
id = "tags"
label = "Tags to stop"
description = "Leave empty to stop all tracking."
type = "string"
position = 1
multiple = true
sources = ["man"]

[[commands.subcommand.task]]
id = "stop_all"
label = "Stop everything"
fields = ["date"]
required = []

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["date", "tags"]

[[commands.subcommand]]
path = ["track"]
label = "Add a past interval"
description = "Record a closed interval in the past."

[[commands.subcommand.source]]
id = "man"
kind = "manual"
url = "https://timewarrior.net/reference/timew-track.1/"
revision = "2026-10-27"
evidence = """
timew track <range> [<tag>…​]
The track command is used to add tracked time in the past.
$ timew track 9am - 11am 'Staff Meeting'
Note that the track command expects a closed interval (start and end time), when recording.
"""

[[commands.subcommand.field]]
id = "range"
label = "Range"
description = "Closed interval, for example: 9am - 11am or :yesterday."
type = "string"
position = 0

sources = ["man"]

[[commands.subcommand.field]]
id = "tags"
label = "Tags"
description = "Tags for the interval."
type = "string"
position = 1
multiple = true
sources = ["man"]

[[commands.subcommand.task]]
id = "track_past"
label = "Record an interval"
fields = ["range", "tags"]
required = ["range"]

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["range", "tags"]

[[commands.subcommand]]
path = ["summary"]
label = "Summary"
description = "Table of tracked time, by default for today."

[[commands.subcommand.source]]
id = "man"
kind = "manual"
url = "https://timewarrior.net/reference/timew-summary.1/"
revision = "2026-10-27"
evidence = """
timew summary [<range>] [<tag>…​]
Displays a table summarizing tracked time, by default for the current day.
Accepts date ranges (or range hints) and tags, or IDs for filtering.
"""

[[commands.subcommand.field]]
id = "range"
label = "Range"
description = "Optional range hint, for example :week or :lastmonth."
type = "string"
position = 0

sources = ["man"]

[[commands.subcommand.field]]
id = "tags"
label = "Tags"
description = "Filter by tags."
type = "string"
position = 1
multiple = true
sources = ["man"]

[[commands.subcommand.task]]
id = "summary_week"
label = "This week"
fields = ["range", "tags"]
required = ["range"]
set = { range = [":week"] }

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["range", "tags"]