id       = "kaggle"
name     = "Kaggle CLI"
homepage = "https://github.com/Kaggle/kaggle-api"
# The repository's own one-line description on github.com/Kaggle/kaggle-api.
description = "Official Kaggle CLI"
icon     = "SimpleIcons:kaggle"
executables   = ["kaggle"]

[dotfiles]

# The Kaggle CLI has no user-level configuration file that is not also the
# credential. docs/configuration.md, "Configuration File Location": "The Kaggle
# CLI configuration is typically stored in a file named kaggle.json located in
# the ~/.kaggle/ directory on Linux and macOS, or C:\Users\<Windows-username>\
# .kaggle\ on Windows." The Windows spelling is the user-profile root, which is
# the same place `~/` names, so there is no second path to list.
#
# `kaggle config set -n competition|path|proxy` writes its three settings into
# that same file, so the settings and the API key share one document; there is
# no second file holding only the settings for `paths` to point at.
paths = []

exclude = []

# Both files are credentials end to end.
#
# docs/configuration.md again: kaggle.json "contains your API username and
# key", and shows the whole document:
#     {"username":"YOUR_USERNAME","key":"YOUR_API_KEY"}
#
# docs/README.md, "Authentication": "Store your Kaggle API token obtained from
# your Kaggle account API tokens settings page in a file at
# ~/.kaggle/access_token", with kaggle.json described alongside it as the
# legacy credential ("Create Legacy API Key"). Both shapes are listed because a
# machine set up before the token file exists still has only kaggle.json.
secret = [
  "~/.kaggle/kaggle.json",
  "~/.kaggle/access_token",
]

[commands]
format = 1
label = "Kaggle CLI"
description = "Download Kaggle datasets and competition data. Submissions, kernels, models and benchmarks are left out."
quality = "ai-draft"
parser = { end_of_options = "--", interleave = "permute", long_equals = true, short_attached = true, short_bundles = false }

[[commands.subcommand]]
path = ["datasets", "download"]
label = "Download a dataset"
description = "Download dataset files; the dataset is owner/dataset-name."

[[commands.subcommand.source]]
id = "docs"
kind = "manual"
url = "https://github.com/Kaggle/kaggle-api/blob/main/docs/datasets.md"
revision = "main 2026-10-27"
evidence = """
kaggle datasets download <DATASET> [options]
*   `<DATASET>`: Dataset URL suffix in the format `owner/dataset-name`
*   `-f, --file <FILE_NAME>`: Specific file to download (downloads all if not specified).
*   `-p, --path <PATH>`: Folder to download files to (defaults to current directory).
*   `--unzip`: Unzip the downloaded file (deletes the .zip file afterwards).
*   `-o, --force`: Force download, overwriting existing files.
*   `-q, --quiet`: Suppress verbose output.
"""

[[commands.subcommand.field]]
id = "dataset"
label = "Dataset (owner/name)"
type = "string"
position = 0
sources = ["docs"]

[[commands.subcommand.field]]
id = "file"
label = "Single file"
description = "Download only this file (all files when empty)."
type = "string"
option = ["--file", "-f"]
sources = ["docs"]

[[commands.subcommand.field]]
id = "path"
label = "Download folder"
type = "path"
option = ["--path", "-p"]
path = { kind = "directory", role = "output" }
sources = ["docs"]

[[commands.subcommand.field]]
id = "unzip"
label = "Unzip after download"
description = "Deletes the .zip file afterwards."
type = "boolean"
option = ["--unzip"]
effect = "delete"
sources = ["docs"]

[[commands.subcommand.field]]
id = "force"
label = "Overwrite existing files"
type = "boolean"
option = ["--force", "-o"]
effect = "overwrite"
sources = ["docs"]

[[commands.subcommand.field]]
id = "quiet"
label = "Quiet"
type = "boolean"
option = ["--quiet", "-q"]
sources = ["docs"]

[[commands.subcommand.task]]
id = "download"
label = "Download and unzip"
set = { unzip = [true] }
fields = ["dataset", "file", "path", "unzip", "force", "quiet"]
required = ["dataset"]

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["dataset", "file", "path", "unzip"]

[[commands.subcommand.group]]
id = "advanced"
label = "Advanced"
fields = ["force", "quiet"]

[[commands.subcommand]]
path = ["competitions", "download"]
label = "Download competition data"
description = "Download competition files."

[[commands.subcommand.source]]
id = "docs"
kind = "manual"
url = "https://github.com/Kaggle/kaggle-api/blob/main/docs/competitions.md"
revision = "main 2026-10-27"
evidence = """
kaggle competitions download <COMPETITION> [options]
*   `<COMPETITION>`: Competition URL suffix (e.g., `titanic`).
*   `-f, --file <FILE_NAME>`: Specific file to download (downloads all if not specified).
*   `-p, --path <PATH>`: Folder to download files to (defaults to current directory).
*   `--unzip`: Unzip the downloaded file (deletes the .zip file afterwards).
*   `-o, --force`: Force download, overwriting existing files.
*   `-q, --quiet`: Suppress verbose output.
"""

[[commands.subcommand.field]]
id = "competition"
label = "Competition"
type = "string"
position = 0
sources = ["docs"]

[[commands.subcommand.field]]
id = "file"
label = "Single file"
description = "Download only this file (all files when empty)."
type = "string"
option = ["--file", "-f"]
sources = ["docs"]

[[commands.subcommand.field]]
id = "path"
label = "Download folder"
type = "path"
option = ["--path", "-p"]
path = { kind = "directory", role = "output" }
sources = ["docs"]

[[commands.subcommand.field]]
id = "unzip"
label = "Unzip after download"
description = "Deletes the .zip file afterwards."
type = "boolean"
option = ["--unzip"]
effect = "delete"
sources = ["docs"]

[[commands.subcommand.field]]
id = "force"
label = "Overwrite existing files"
type = "boolean"
option = ["--force", "-o"]
effect = "overwrite"
sources = ["docs"]

[[commands.subcommand.field]]
id = "quiet"
label = "Quiet"
type = "boolean"
option = ["--quiet", "-q"]
sources = ["docs"]

[[commands.subcommand.task]]
id = "download"
label = "Download and unzip"
set = { unzip = [true] }
fields = ["competition", "file", "path", "unzip", "force", "quiet"]
required = ["competition"]

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["competition", "file", "path", "unzip"]

[[commands.subcommand.group]]
id = "advanced"
label = "Advanced"
fields = ["force", "quiet"]