id = "khal"
name = "khal"
homepage = "https://lostpackets.de/khal/"
description = "A command-line calendar application"
executables = ["khal", "ikhal"]

[dotfiles]

# khal's usage guide documents ~/.khal/khal.conf and ~/.config/khal/khal.conf
# as user config locations. The current config spec uses the XDG path
# $XDG_CONFIG_HOME/khal/config; its cache default is $XDG_CACHE_HOME/khal/khal.db.
# https://lostpackets.de/khal/pages/usage.html
# https://github.com/pimutils/khal/blob/master/khal/settings/khal.spec
paths = [
  "~/.khal/khal.conf",
  "[configHome]/khal/config",
  "[configHome]/khal/khal.conf",
  "[xdgCache]/khal/khal.db",
]
secret = []

[commands]
format = 1
label = "khal calendar"
description = "List events in a date range or add a new event to a calendar. Editing, importing, search and the interactive UI are left out."
quality = "ai-draft"
parser = { end_of_options = "--", interleave = "permute", long_equals = true, short_attached = false, short_bundles = false }

[[commands.source]]
id = "doc"
kind = "manual"
url = "https://lostpackets.de/khal/"
revision = "usage.rst master 2026-10"
evidence = """
khal list [-a CALENDAR ... | -d CALENDAR ...]
[--format FORMAT] [--json FIELD ...] [--day-format DAYFORMAT]
[--once] [--notstarted] [START [END | DELTA] ]
khal list -a soccer today 30d
.. option:: --format FORMAT
.. option:: -a CALENDAR
.. option:: -d CALENDAR
"""

[[commands.subcommand]]
path = ["list"]
label = "List events"

[[commands.subcommand.source]]
id = "doc"
kind = "manual"
url = "https://github.com/pimutils/khal/blob/master/doc/source/usage.rst"
revision = "master 2026-10"
evidence = """
khal list [-a CALENDAR ... | -d CALENDAR ...]
[--format FORMAT] [--json FIELD ...] [--day-format DAYFORMAT]
[--once] [--notstarted] [START [END | DELTA] ]
khal list -a soccer today 30d
.. option:: --format FORMAT
.. option:: -a CALENDAR
.. option:: -d CALENDAR
"""

[[commands.subcommand.field]]
id = "range"
label = "Start, end or delta"
description = "For example: today 30d, or 2019-12-01 31d."
type = "string"
position = 0
multiple = true
sources = ["doc"]

[[commands.subcommand.field]]
id = "include"
label = "Only these calendars"
type = "string"
option = ["-a"]
multiple = true
sources = ["doc"]

[[commands.subcommand.field]]
id = "exclude"
label = "Exclude these calendars"
type = "string"
option = ["-d"]
multiple = true
sources = ["doc"]

[[commands.subcommand.field]]
id = "format"
label = "Output format"
description = "For example: {title} {description}."
type = "string"
option = ["--format"]
sources = ["doc"]

[[commands.subcommand.task]]
id = "upcoming"
label = "Upcoming events"
fields = ["range", "include"]
required = []
set = { range = ["today", "30d"] }

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["range", "include", "exclude", "format"]

[[commands.subcommand]]
path = ["new"]
label = "Add an event"

[[commands.subcommand.source]]
id = "doc"
kind = "manual"
url = "https://github.com/pimutils/khal/blob/master/doc/source/usage.rst"
revision = "master 2026-10"
evidence = """
khal new [-a CALENDAR] [OPTIONS] [START [END | DELTA] [TIMEZONE] SUMMARY
[:: DESCRIPTION]]
* **-l, --location=LOCATION** specify where this event will be held.
* **-g, --categories=CATEGORIES** specify which categories this event belongs to.
* **-r, --repeat=RRULE** specify if and how this event should be recurring.
  Valid values for *RRULE* are `daily`, `weekly`, `monthly`
  and `yearly`
* **-u, --until=UNTIL** specify until when a recurring event should run
.. option:: -a CALENDAR
khal new 18:00 Awesome Event
khal new -a work 26.07. Great Event -g meeting -r weekly
"""

[[commands.subcommand.field]]
id = "event"
label = "Start, end, timezone and summary"
description = "For example: tomorrow 16:30 Coffee Break. Text after :: becomes the description."
type = "string"
position = 0
multiple = true
sources = ["doc"]

[[commands.subcommand.field]]
id = "calendar"
label = "Calendar"
description = "The default calendar is used when empty."
type = "string"
option = ["-a"]
sources = ["doc"]

[[commands.subcommand.field]]
id = "location"
label = "Location"
type = "string"
option = ["--location", "-l"]
sources = ["doc"]

[[commands.subcommand.field]]
id = "categories"
label = "Categories"
description = "Comma separated."
type = "string"
option = ["--categories", "-g"]
sources = ["doc"]

[[commands.subcommand.field]]
id = "repeat"
label = "Repeat"
type = "enum"
option = ["--repeat", "-r"]
choices = [{ value = "daily", label = "Daily" }, { value = "weekly", label = "Weekly" }, { value = "monthly", label = "Monthly" }, { value = "yearly", label = "Yearly" }]
sources = ["doc"]

[[commands.subcommand.field]]
id = "until"
label = "Repeat until"
type = "string"
option = ["--until", "-u"]
sources = ["doc"]

[[commands.subcommand.task]]
id = "add"
label = "Add an event"
fields = ["event", "calendar", "location"]
required = ["event"]

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["event", "calendar", "location"]

[[commands.subcommand.group]]
id = "advanced"
label = "Advanced"
fields = ["categories", "repeat", "until"]