id = "twarc"
name = "twarc"
homepage = "https://twarc-project.readthedocs.io/"
description = "Command-line and Python tools for archiving Twitter/X data."
executables = ["twarc"]

[dotfiles]

# Twarc's official documentation says `twarc configure` stores its credentials
# in ~/.twarc; the API reference's default_config helper confirms that path.
# https://twarc-project.readthedocs.io/en/latest/twarc1_en_us/
# https://twarc-project.readthedocs.io/en/latest/api/client/
paths = []
secret = ["~/.twarc"]

[commands]
format = 1
label = "twarc"
description = "Collect tweets with the v1.1 twarc command. Only search is modelled; filter, timeline, hydrate and the premium-archive options are left out."
quality = "ai-draft"
parser = { end_of_options = "--", interleave = "permute", long_equals = true, short_attached = false, short_bundles = false }

[[commands.subcommand]]
path = ["search"]
label = "Search tweets"
description = "Search recent tweets. Output goes to stdout; redirect it to a .jsonl file in the shell."

[[commands.subcommand.source]]
id = "docs"
kind = "manual"
url = "https://twarc-project.readthedocs.io/en/latest/twarc1_en_us/"
revision = "2026-10-27"
evidence = """
twarc search blacklivesmatter > tweets.jsonl
twarc search '#blacklivesmatter' --lang fr > tweets.jsonl
twarc search blacklivesmatter --geocode 38.7442,-90.3054,1mi > tweets.jsonl
If a search query isn't supplied when using --geocode you will get all tweets relevant for that location and radius
you will likely want to limit the time range using --to_date and --from_date. Additionally you can limit the maximum number of tweets returned using --limit.
"""

[[commands.subcommand.field]]
id = "query"
label = "Query"
description = "Search terms, for example '#blacklivesmatter OR #blm'. Optional when a geocode is given."
type = "string"
position = 0
sources = ["docs"]

[[commands.subcommand.field]]
id = "lang"
label = "Language (ISO 639-1)"
type = "string"
option = ["--lang"]
sources = ["docs"]

[[commands.subcommand.field]]
id = "geocode"
label = "Geocode"
description = "latitude,longitude,radius, for example 38.7442,-90.3054,1mi."
type = "string"
option = ["--geocode"]
sources = ["docs"]

[[commands.subcommand.field]]
id = "from_date"
label = "From date"
type = "string"
option = ["--from_date"]
sources = ["docs"]

[[commands.subcommand.field]]
id = "to_date"
label = "To date"
type = "string"
option = ["--to_date"]
sources = ["docs"]

[[commands.subcommand.field]]
id = "limit"
label = "Maximum tweets"
type = "integer"
option = ["--limit"]
sources = ["docs"]

[[commands.subcommand.task]]
id = "search_query"
label = "Search a query"
fields = ["query", "lang", "limit"]
required = ["query"]

[[commands.subcommand.task]]
id = "search_near"
label = "Search near a location"
fields = ["query", "geocode", "limit"]
required = ["geocode"]

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["query", "lang", "geocode", "limit"]

[[commands.subcommand.group]]
id = "advanced"
label = "Advanced"
fields = ["from_date", "to_date"]