kaggle 2.2.1__tar.gz → 2.2.3__tar.gz

{kaggle-2.2.1 → kaggle-2.2.3}/.gitignore

@@ -49,6 +49,7 @@ coverage.xml
 *,cover
 .hypothesis/
 venv/
+.venv
 .python-version
 
 # Translations

{kaggle-2.2.1 → kaggle-2.2.3}/CHANGELOG.md

@@ -3,6 +3,29 @@ Changelog
 
 ### Next
 
+### 2.2.3
+
+* Update --format help text to reference output_format.md (#1074)
+* Update kernel pull docs with version example (#1072)
+* Reorganize tests and rename unit_tests.py to backend_tests.py (#1071)
+* Add support for formatting projections (#1068)
+* Rewrite `kaggle kernels logs --follow` to use SSE log stream (#999)
+* Add --format option to CLI commands supporting --csv (#1062)
+
+### 2.2.2
+
+* Clarify LLMS_AVAILABLE vs. full model set in benchmarks docs (#1061)
+* Add kernels topics command (#1056)
+* Improve benchmark task error messages in kaggle CLI (#1057)
+* Fix dataset metadata column/file description updates and docs (#1055)
+* Expand Kaggle CLI skill references (#1054)
+* Tag benchmarks token requests with CLI source for analytics (#1050)
+* Add machine_shape to kernels_initialize metadata template and docs (#1048)
+* Fix 403 for dataset, model, and benchmark topics list (#1051)
+* Fix test_benchmarks_cli.py assertions (#1049)
+* Add paginated downloads for kernel output files (#1046)
+* fix(tests): resolve infinite loop in test_kernels_d_status (#1043)
+
 ### 2.2.1
 
 * Add `kaggle competitions team-submissions` command (#1036)

{kaggle-2.2.1 → kaggle-2.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kaggle
-Version: 2.2.1
+Version: 2.2.3
 Summary: Access Kaggle resources anywhere
 Project-URL: Homepage, https://github.com/Kaggle/kaggle-cli
 Project-URL: Issues, https://github.com/Kaggle/kaggle-cli/issues
@@ -214,7 +214,7 @@ Classifier: Programming Language :: Python :: 3
 Requires-Python: >=3.11
 Requires-Dist: bleach
 Requires-Dist: jupytext
-Requires-Dist: kagglesdk<1.0,>=0.1.27
+Requires-Dist: kagglesdk<1.0,>=0.1.30
 Requires-Dist: packaging
 Requires-Dist: protobuf
 Requires-Dist: python-dateutil

{kaggle-2.2.1 → kaggle-2.2.3}/docs/README.md

@@ -62,6 +62,10 @@ The Kaggle CLI is organized into several command groups:
 *   [Benchmarks](./benchmarks.md): Define evaluation tasks, run them against LLM models, and download results.
 *   [Configuration](./configuration.md): Configure the Kaggle CLI.
 
+Many commands produce output, which can be formatted for different purposes:
+
+*   [Output Format](./output_format.md): Control the format of output.
+
 ## Tutorials
 
 Explore these tutorials to learn how to perform common tasks:

{kaggle-2.2.1 → kaggle-2.2.3}/docs/benchmarks.md

@@ -77,6 +77,8 @@ In addition to the three credential variables written by `auth`, `init` also wri
 *   `LLM_DEFAULT_EVAL` — Default model slug for evaluation.
 *   `LLMS_AVAILABLE` — Comma-separated list of available model slugs.
 
+> **Note:** `LLMS_AVAILABLE` is a curated subset of models intended for local development and testing — it is **not** the full set of available models, and the Model Proxy token itself is not restricted to these models. To see all available models, use `kaggle benchmarks tasks models`. To run a task against any model (including those not in `LLMS_AVAILABLE`), use `kaggle benchmarks tasks run`, which executes on Kaggle's infrastructure with access to the full model catalog.
+
 `init` also creates two files alongside the example file:
 
 *   **`example_task.py`** (or custom name via `--example-file`) — A starter Python script demonstrating how to define a benchmark task using `@task` decorators and the `kaggle_benchmarks` library.
@@ -271,6 +273,8 @@ kaggle benchmarks tasks status <TASK> [options]
 
 Prints the task's metadata (slug, creation status, creation time, URL) followed by a table of all runs. Each run row shows the model name, run state, start time, and end time. Any errored runs display their error messages below the table.
 
+If task creation itself failed, the `Status:` line shows the failure *kind* — the cleaned creation-state enum, titlecased (e.g. `Kernel_Without_Run`, `No_Model_Specified`, `Validation_Failed`, `Errored`) — and an `Error:` line is appended below it with the server-provided `creation_error_message` explaining what went wrong.
+
 ---
 
 ### `kaggle benchmarks tasks download`

{kaggle-2.2.1 → kaggle-2.2.3}/docs/datasets_metadata.md

@@ -74,7 +74,7 @@ The following metadata is currently supported:
     * `schema`: File schema (definition below):
       * `fields`: Array of fields in the dataset.  Please note that this needs to include ALL of the fields in the data in order or they will not be matched up correctly.  A later version of the API will fix this bug.
         * `name`: Field name
-        * `title`: Field description
+        * `description`: Field description (Note: `title` is also accepted for backward compatibility, but `description` is preferred)
         * `type`: Field type. A best-effort list of types will be kept at the bottom of this page, but new types may be added that are not documented here.
   * `keywords`: Contains an array of strings that correspond to an existing tag on Kaggle.  If a specified tag doesn't exist, the upload will continue, but that specific tag won't be added.  
 * `kaggle datasets version` (create a new version for an existing Dataset):
@@ -88,7 +88,7 @@ The following metadata is currently supported:
     * `schema`: File schema (definition below):
       * `fields`: Array of fields in the dataset.  Please note that this needs to include ALL of the fields in the data in order or they will not be matched up correctly.  A later version of the API will fix this bug.
         * `name`: Field name
-        * `title`: Field description
+        * `description`: Field description (Note: `title` is also accepted for backward compatibility, but `description` is preferred)
         * `type`: Field type. A best-effort list of types will be kept at the bottom of this page, but new types may be added that are not documented here.
   * `keywords`: Contains an array of strings that correspond to an existing tag on Kaggle.  If a specified tag doesn't exist, the upload will continue, but that specific tag won't be added.  
 * `kaggle datasets metadata --update` (update metadata for an existing Dataset) supports all fields mentioned above for `kaggle datasets version`, and additionally:

{kaggle-2.2.1 → kaggle-2.2.3}/docs/kernels.md

@@ -179,7 +179,7 @@ kaggle kernels pull <KERNEL> [options]
 
 **Arguments:**
 
-*   `<KERNEL>`: Kernel URL suffix (format: `owner/kernel-slug`, e.g., `$KAGGLE_DEVELOPER/exercise-as-with`).
+*   `<KERNEL>`: Kernel URL suffix (format: `owner/kernel-slug` or `owner/kernel-slug/version`, e.g., `$KAGGLE_DEVELOPER/exercise-as-with` or `$KAGGLE_DEVELOPER/exercise-as-with/2`).
 
 **Options:**
 
@@ -201,6 +201,12 @@ kaggle kernels pull <KERNEL> [options]
     kaggle kernels pull --wp $KAGGLE_DEVELOPER/exercise-as-with
     ```
 
+3.  Pull version 2 of the kernel `$KAGGLE_DEVELOPER/exercise-as-with` into the current working directory:
+
+    ```bash
+    kaggle kernels pull --wp $KAGGLE_DEVELOPER/exercise-as-with/2
+    ```
+
 **Purpose:**
 
 This command allows you to download the source code and optionally the metadata of a kernel from Kaggle to your local machine.
@@ -226,6 +232,8 @@ kaggle kernels output <KERNEL> [options]
 *   `-o, --force`: Force download, overwriting existing files.
 *   `-q, --quiet`: Suppress verbose output.
 *   `--file-pattern <REGEX>`: Regex pattern to match against filenames. Only files matching the pattern will be downloaded.
+*   `--page-size <SIZE>`: Number of output files to request per page. Default size is 20, max is 200.
+*   `--page-token <TOKEN>`: Download files from a specific output page. If Kaggle returns another page token, it is printed after the download.
 
 **Example:**
 
@@ -240,9 +248,27 @@ Download PNG files only:
 kaggle kernels output <kernel> --file-pattern ".*\.png$"  # Only PNG files
 ```
 
+Download matching PNG files across all output pages:
+
+```bash
+kaggle kernels output <kernel> --file-pattern ".*\.png$"
+```
+
+Download files from a specific output page:
+
+```bash
+kaggle kernels output <kernel> --page-token <TOKEN>
+```
+
+Download files in smaller pages:
+
+```bash
+kaggle kernels output <kernel> --page-size 50
+```
+
 **Purpose:**
 
-Use this command to retrieve the files generated by a kernel run, such as submission files, processed data, or visualizations.
+Use this command to retrieve the files generated by a kernel run, such as submission files, processed data, or visualizations. By default, output downloads scan every available output page, so `--file-pattern` can match files beyond the first page. Use `--page-size` to control how many files are requested on each page, and use `--page-token` when you only want to download files from one specific page.
 
 ## `kaggle kernels status`
 
@@ -299,3 +325,72 @@ kaggle kernels delete $KAGGLE_DEVELOPER/exercise-delete --yes
 **Purpose:**
 
 This command permanently removes one of your kernels from Kaggle. Use with caution.
+
+## `kaggle kernels topics list`
+
+Lists discussion topics for a kernel.
+
+**Usage:**
+
+```bash
+kaggle kernels topics list <KERNEL> [options]
+```
+
+**Arguments:**
+
+*   `<KERNEL>`: Kernel ref in format `<owner>/<kernel-slug>` (e.g., `owner/kernel-slug`).
+
+**Options:**
+
+*   `--sort-by <SORT_BY>`: Sort order. Valid options: `hot`, `top`, `new`, `recent`, `active`, `relevance`.
+*   `-s, --search <SEARCH_TERM>`: Search query to filter topics.
+*   `--page-size <PAGE_SIZE>`: Number of items per page.
+*   `--page-token <PAGE_TOKEN>`: Page token for pagination.
+*   `-v, --csv`: Print results in CSV format.
+*   `-q, --quiet`: Suppress verbose output.
+
+**Example:**
+
+List recent topics for the `owner/kernel-slug` kernel:
+
+```bash
+kaggle kernels topics list owner/kernel-slug --sort-by recent
+```
+
+**Purpose:**
+
+This command lets you browse discussion topics for a specific kernel.
+
+## `kaggle kernels topics show`
+
+Displays a kernel discussion topic with all comments in tree form.
+
+**Usage:**
+
+```bash
+kaggle kernels topics show <TOPIC_REF> [options]
+```
+
+**Arguments:**
+
+*   `<TOPIC_REF>`: A topic reference, which can be:
+    *   `<kernel>/<topic-id>` (e.g., `owner/kernel-slug/12345`)
+    *   `<kernel> <topic-id>` (two separate arguments, where `<topic-id>` is passed as second argument)
+    *   `<topic-id>` (bare numeric ID)
+
+**Options:**
+
+*   `--page-size <PAGE_SIZE>`: Number of comments to show per page.
+*   `--page-token <PAGE_TOKEN>`: Page token for comment pagination.
+*   `-v, --csv`: Print results in CSV format.
+*   `-q, --quiet`: Suppress verbose output.
+
+**Example:**
+
+```bash
+kaggle kernels topics show owner/kernel-slug/12345
+```
+
+**Purpose:**
+
+This command displays a full discussion topic along with all of its comments rendered in an indented tree structure.

{kaggle-2.2.1 → kaggle-2.2.3}/docs/kernels_metadata.md

@@ -12,6 +12,7 @@ Here's a basic example for `kernel-metadata.json`:
   "is_private": "false",
   "enable_gpu": "false",
   "enable_internet": "false",
+  "machine_shape": "",
   "dataset_sources": ["timoboz/my-awesome-dataset"],
   "competition_sources": [],
   "kernel_sources": [],
@@ -34,6 +35,7 @@ We currently support the following metadata fields for kernels.
 * `is_private`: Whether or not the kernel should be private. If not specified, will be `true`.
 * `enable_gpu`: Whether or not the kernel should run on a GPU. If not specified, will be `false`.
 * `enable_internet`: Whether or not the kernel should be able to access the internet. If not specified, will be `false`.
+* `machine_shape`: The accelerator/GPU type to use (e.g., `NvidiaTeslaT4`, `NvidiaTeslaP100`, or `Tpu1VmV38`).
 * `dataset_sources`: A list of dataset sources, specified as `"username/dataset-slug"`
 * `competition_sources`: A list of competition sources, specified as `"competition-slug"`
 * `kernel_sources`: A list of kernel sources, specified as `"username/kernel-slug"`

kaggle-2.2.3/docs/output_format.md

@@ -0,0 +1,140 @@
+# Kaggle CLI Output Formatting Documentation
+
+This documentation describes the output formatting options available in the Kaggle CLI.
+
+## Output Format Options
+
+The Kaggle CLI supports choosing the output format for various commands that list information.
+
+### `--csv` (or `-v`)
+
+Historically, many commands supported a `-v` or `--csv` option to display output as comma-separated values (CSV) instead of a formatted table.
+
+Example:
+```sh
+kaggle competitions list --csv
+```
+
+### `--format`
+
+We have introduced a new `--format` option to provide a unified way to specify the output format.
+It accepts the following values:
+*   `csv`: Display output as comma-separated values.
+*   `table`: Display output as a formatted table (default).
+*   `json`: Display output as JSON.
+
+Example:
+```sh
+kaggle competitions list --format csv
+kaggle competitions list --format table
+kaggle competitions list --format json
+```
+
+For most commands, the JSON output is a list of objects representing the rows, with keys corresponding to the column headers. For detailed commands like `topics show`, it returns a structured object:
+```json
+{
+  "topic": { ... },
+  "comments": [ ... ]
+}
+```
+
+### Projections (Field Selection)
+
+The `--format` option supports optional `gcloud`-style field selection (projections) by appending a comma-separated list of fields in parentheses to the format name. This allows you to limit the output to only the specified fields and control their order.
+
+Projections are supported for all formats (`csv`, `table`, `json`).
+
+Example:
+```sh
+# Only show 'ref' and 'reward' columns for competitions in a table
+kaggle competitions list --format "table(ref,reward)"
+
+# Export only 'id' and 'publicScore' to JSON for team submissions
+kaggle competitions team-submissions --format "json(id,publicScore)" <team_id>
+
+# Export only 'name' and 'size' to CSV for dataset files
+kaggle datasets files -d zillow/zecon --format "csv(name,size)"
+```
+
+You can specify fields using either their field names (e.g. `totalBytes`) or their display labels (e.g. `size`). If a field is not recognized, the CLI will display an error listing the allowed fields.
+
+#### Special Case: Topics Show
+
+For `topics show` commands, which output both a parent topic and a list of comments, the projection is applied to both types of objects. Fields matching the topic are applied to the topic output, and fields matching comments are applied to the comment output.
+
+Example:
+```sh
+kaggle forums topics show 123 --format "json(title,content)"
+```
+In this case, `title` (which is a topic field) will be preserved in the topic output, and `content` (which is a comment field) will be preserved in the comments output.
+```json
+{
+  "topic": {
+    "title": "Test Title"
+  },
+  "comments": [
+    {
+      "content": "Comment Content"
+    }
+  ]
+}
+```
+
+### Mutual Exclusion
+
+The `--csv` (or `-v`) option and the `--format` option are **mutually exclusive**. You cannot specify both at the same time.
+
+If you attempt to use both, the CLI will display an error:
+```sh
+kaggle competitions list --csv --format csv
+# Error: argument --format: not allowed with argument -v/--csv
+```
+
+## Supported Commands
+
+The following commands support both `--csv` (legacy) and `--format` options:
+
+### Competitions
+*   `kaggle competitions list`
+*   `kaggle competitions files`
+*   `kaggle competitions submissions`
+*   `kaggle competitions leaderboard`
+*   `kaggle competitions team-submissions`
+*   `kaggle competitions episodes`
+*   `kaggle competitions pages`
+*   `kaggle competitions topic-messages`
+*   `kaggle competitions topics list`
+*   `kaggle competitions topics show`
+
+### Datasets
+*   `kaggle datasets list`
+*   `kaggle datasets files`
+*   `kaggle datasets topics list`
+*   `kaggle datasets topics show`
+
+### Kernels
+*   `kaggle kernels list`
+*   `kaggle kernels files`
+*   `kaggle kernels topics list`
+*   `kaggle kernels topics show`
+
+### Models
+*   `kaggle models list`
+*   `kaggle models topics list`
+*   `kaggle models topics show`
+*   `kaggle models instances list`
+*   `kaggle models instances files`
+*   `kaggle models instances versions list`
+*   `kaggle models instances versions files`
+
+### Forums
+*   `kaggle forums list`
+*   `kaggle forums topics list`
+*   `kaggle forums topics show`
+
+### Benchmarks
+*   `kaggle benchmarks topics list`
+*   `kaggle benchmarks topics show`
+
+### Quota
+*   `kaggle quota`

{kaggle-2.2.1 → kaggle-2.2.3}/pyproject.toml

@@ -24,7 +24,7 @@ keywords = ["Kaggle", "API"]
 requires-python = ">= 3.11"
 dependencies = [
     "bleach",
-    "kagglesdk >= 0.1.27, < 1.0", # sync with kagglehub
+    "kagglesdk >= 0.1.30, < 1.0", # sync with kagglehub
     "python-slugify",
     "requests",
     "python-dateutil",
@@ -55,9 +55,9 @@ dependencies = [
 ]
 
 [tool.hatch.envs.test.scripts]
-local = "source tools/use-localhost.sh; cd tests; python unit_tests.py --failfast"
-prod = "source tools/use-prod.sh; cd tests; python unit_tests.py --failfast"
-integration = "pytest integration_tests"
+local = "source tools/use-localhost.sh; cd tests/backend; python backend_tests.py --failfast"
+prod = "source tools/use-prod.sh; cd tests/backend; python backend_tests.py --failfast"
+integration = "pytest tests/integration"
 
 [tool.hatch.envs.lint]
 detached = true
@@ -105,7 +105,6 @@ ignore_missing_imports = true
 
 [tool.pytest.ini_options]
 testpaths = [
-    "src/kaggle/test",
-    "tests",
+    "tests/unit",
 ]
 pythonpath = ["src"]

kaggle-2.2.3/skills/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: kaggle-cli
+description: >
+  Use the local Kaggle CLI skill for command guidance, workflows, and
+  troubleshooting across competitions, datasets, kernels/notebooks, models,
+  model variations and versions, inbox file uploads, forums/discussions,
+  benchmarks, configuration, OAuth/API-token authentication, and accelerator
+  quota. Activate this skill when the user asks about kaggle CLI commands,
+  examples, flags, metadata files, download/upload flows, submissions,
+  benchmark tasks, or Kaggle CLI behavior.
+---
+
+# Kaggle CLI
+
+Use this skill to answer or operate on the `kaggle` command-line tool. Treat
+this skill and its references as the available command guide.
+
+## Quick Start
+
+```bash
+pip install kaggle
+kaggle --help
+```
+
+Authentication options:
+
+```bash
+kaggle auth login
+# or set KAGGLE_API_TOKEN
+# or place an access token in ~/.kaggle/access_token
+# or use legacy ~/.kaggle/kaggle.json credentials
+```
+
+## Command Tree
+
+```text
+kaggle
+├── competitions | c
+│   ├── list, files, download, submit, submissions, leaderboard
+│   ├── team-submissions, episodes, replay, logs, pages
+│   └── topics {list, show}, topic-messages
+├── datasets | d
+│   ├── list, files, download, init, create, version
+│   ├── metadata, status, delete
+│   └── topics {list, show}
+├── kernels | k
+│   └── list, files, init, push|update, pull|get, output, status, logs, delete
+├── models | m
+│   ├── list, init, create, get, update, delete
+│   ├── topics {list, show}
+│   └── variations | instances | v | i
+│       ├── get, init, create, files, list, update, delete
+│       └── versions | v {list, create, download, files, delete}
+├── files {upload}
+├── forums | f {list, topics {list, show}}
+├── benchmarks | b
+│   ├── auth, init
+│   ├── tasks | t {push, run, list, status, download, log|logs, models, delete, publish}
+│   └── topics {list, show}
+├── config {view, set, unset}
+├── auth {login, print-access-token, revoke}
+└── quota
+```
+
+Note: the CLI accepts aliases such as `kernels get` for `kernels pull` and
+`kernels update` for `kernels push`. Do not recommend
+`models variations versions init`; use `models variations init` for variation
+metadata instead.
+
+## Reference Map
+
+Read only the reference needed for the user's task:
+
+- [Competitions](references/competitions.md) - competition discovery, files, downloads, submissions, leaderboards, simulations, pages, topics.
+- [Datasets](references/datasets.md) - dataset search, files, downloads, metadata, create/version/status/delete, topics.
+- [Kernels](references/kernels.md) - notebook/script discovery, metadata, push/pull, outputs, status, logs, delete.
+- [Models](references/models.md) - model records, metadata, create/get/update/delete, model topics.
+- [Model Variations](references/model_variations.md) - create and manage framework-specific model variations.
+- [Model Variation Versions](references/model_variations_versions.md) - create, list, download, inspect, and delete variation versions.
+- [Files](references/files.md) - inbox uploads, resumable uploads, directory compression behavior.
+- [Forums](references/forums.md) - global discussion forums, topics, and comments.
+- [Benchmarks](references/benchmarks.md) - benchmark auth/init, task push/run/status/download/log/model flows, benchmark topics.
+- [Configuration](references/configuration.md) - config file, default path, proxy, default competition.
+- [Authentication](references/auth.md) - OAuth login, access token printing, revocation, token/key sources.
+- [Quota](references/quota.md) - weekly GPU/TPU accelerator quota.
+
+## Operating Guidance
+
+- Read only the reference needed for the user's task.
+- Prefer `kaggle <group> --help` or `kaggle <group> <command> --help` when a flag
+  is uncertain in the installed CLI.
+- For metadata files, prefer the relevant `init` command to generate a starter
+  file before editing it.
+- Do not invent commands that are not listed in this skill. If live `--help`
+  output differs, report it as a version-specific difference.

kaggle-2.2.3/skills/references/auth.md

@@ -0,0 +1,137 @@
+# Authentication CLI Reference
+
+Use `kaggle auth` to run OAuth login, print an OAuth access token, or revoke the
+active OAuth refresh token. The CLI also supports non-command authentication via
+`KAGGLE_API_TOKEN`, `~/.kaggle/access_token`, and legacy API key credentials.
+
+## Prerequisites
+
+- Python 3.11+ with the `kaggle` package installed.
+- A Kaggle account.
+- Browser access for the default OAuth login flow, or use `--no-launch-browser`
+  to print a URL.
+
+## Command Hierarchy
+
+```text
+kaggle auth
+├── login
+├── print-access-token
+└── revoke
+```
+
+## Authentication Sources
+
+The CLI authentication flow tries these sources:
+
+1. Access token sources such as `KAGGLE_API_TOKEN` or
+   `~/.kaggle/access_token`.
+2. Legacy API key config from environment/config values `username` and `key`.
+3. OAuth credentials created by `kaggle auth login`.
+
+If none succeed, the CLI prints auth help and exits.
+
+Some commands are allowed logged out, including help/version and selected
+public dataset file/download flows.
+
+## `kaggle auth login`
+
+Runs Kaggle OAuth login.
+
+**Usage:**
+
+```bash
+kaggle auth login [options]
+```
+
+**Options:**
+
+- `--no-launch-browser`: Do not launch a browser; print an auth URL instead.
+- `--force`: Re-run login even if already logged in.
+
+**Examples:**
+
+```bash
+kaggle auth login
+kaggle auth login --no-launch-browser
+kaggle auth login --force
+```
+
+**Purpose:** Store OAuth credentials for the active Kaggle account.
+
+**Behavior details:**
+
+- If credentials already exist and `--force` is not set, the command prints the
+  current account and exits with instructions to use `--force`.
+- The OAuth flow requests the default scope `resources.admin:*`.
+
+## `kaggle auth print-access-token`
+
+Prints an access token for the active OAuth account.
+
+**Usage:**
+
+```bash
+kaggle auth print-access-token [options]
+```
+
+**Options:**
+
+- `--expiration <DURATION>`: Override token duration.
+
+**Examples:**
+
+```bash
+kaggle auth print-access-token
+```
+
+**Purpose:** Emit a token that can be placed in `KAGGLE_API_TOKEN` or another
+supported token source.
+
+**Behavior details:**
+
+- Requires OAuth credentials from `kaggle auth login`.
+- If no OAuth credentials exist, the command tells the user to run
+  `kaggle auth login`.
+- Some CLI help examples use short forms such as `6h`. For automation, omit
+  `--expiration` unless the accepted duration format has been verified with
+  the installed CLI.
+
+## `kaggle auth revoke`
+
+Revokes the active OAuth refresh token.
+
+**Usage:**
+
+```bash
+kaggle auth revoke [options]
+```
+
+**Options:**
+
+- `--reason <TEXT>`: Reason sent to the server.
+
+**Examples:**
+
+```bash
+kaggle auth revoke
+kaggle auth revoke --reason "rotating credentials"
+```
+
+**Purpose:** Invalidate the active OAuth credential.
+
+**Behavior details:**
+
+- If no OAuth credentials exist, the command prints `There is no token to
+  revoke.` and exits successfully.
+- If no reason is provided, the default reason is
+  `Manually revoked by user with kaggle-cli`.
+
+## Legacy And Token Auth Notes
+
+- `KAGGLE_API_TOKEN` can authenticate without a legacy username/key pair when
+  the token introspection succeeds.
+- Legacy config can come from `~/.kaggle/kaggle.json` or environment variables
+  such as `KAGGLE_USERNAME` and `KAGGLE_KEY`.
+- Prefer `kaggle auth login` for OAuth credentials or `KAGGLE_API_TOKEN` for
+  non-interactive authentication.