kaggle 2.1.2__tar.gz → 2.2.0__tar.gz

kaggle-2.2.0/.gcloudignore

@@ -0,0 +1,12 @@
+# Source control
+.git/
+.github/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+
+# Builds & related cache
+dist/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/

{kaggle-2.1.2 → kaggle-2.2.0}/.gitignore

@@ -79,3 +79,6 @@ target/
 
 # Kagent
 .kagent-context/**
+
+# Jetski
+.jetskicli/

{kaggle-2.1.2 → kaggle-2.2.0}/CHANGELOG.md

@@ -3,6 +3,14 @@ Changelog
 
 ### Next
 
+### 2.2.0
+
+* Add test runner workflow
+* Patch discussions code (#1018)
+* fix(benchmarks): normalize provider-prefixed and @-containing model s… (#1016)
+* fix(benchmarks): handle EOF when selecting models without -m (#1013)
+* fix(benchmarks): dual layer rate limiting (#1014)
+* Small changes to improve debugging (#1008)
 * feat: add forums commands for browsing Kaggle discussions (#993)
 * Add competitions topics CLI command (#982)
 

{kaggle-2.1.2 → kaggle-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kaggle
-Version: 2.1.2
+Version: 2.2.0
 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.23
+Requires-Dist: kagglesdk<1.0,>=0.1.24
 Requires-Dist: packaging
 Requires-Dist: protobuf
 Requires-Dist: python-dateutil

{kaggle-2.1.2 → kaggle-2.2.0}/docs/benchmarks.md

@@ -6,7 +6,7 @@ The top-level command is `kaggle benchmarks` (alias: `kaggle b`), which has thre
 
 *   **`auth`** — Fetch Model Proxy credentials.
 *   **`init`** — Fetch credentials and default environment variables for local development.
-*   **`tasks`** (alias: `t`) — Manage benchmark tasks (push, run, list, status, download, models, delete).
+*   **`tasks`** (alias: `t`) — Manage benchmark tasks (push, run, list, status, download, log, models, delete, publish).
 
 ## `kaggle benchmarks auth`
 
@@ -108,7 +108,10 @@ kaggle benchmarks tasks push <TASK> -f <FILE> [options]
 
 *   `-f, --file <FILE>` *(required)*: Path to the source Python file defining the task.
 *   `--wait [TIMEOUT]`: Wait for the task creation to complete. Optionally specify a timeout in seconds (`0` or omit value = wait indefinitely).
-*   `--poll-interval <SECONDS>`: Seconds between status polls when using `--wait` (default: `10`).
+*   `--poll-interval <SECONDS>`: Maximum seconds between status polls (default: `60`). Polling starts at 5s and increases by 50% each iteration until reaching this value.
+*   `-v, --verbose`: Enable verbose polling logs.
+*   `-d, --kaggle-dataset <DATASET>`: Kaggle dataset to attach to the task's underlying notebook (format: `owner/dataset-slug`). Repeat for multiple datasets (e.g. `-d kaggle/titanic -d user/my-dataset`). Mounted at `/kaggle/input/<dataset-slug>/` by default. If a naming conflict occurs, the fully qualified mount path `/kaggle/input/<owner>/<dataset-slug>/` is used instead.
+
 
 **Examples:**
 
@@ -125,14 +128,28 @@ kaggle benchmarks tasks push <TASK> -f <FILE> [options]
     ```
 
 3.  Push a task and wait with a 60-second timeout, polling every 5 seconds:
-
-    ```bash
-    kaggle b t push my-task -f benchmark.py --wait 60 --poll-interval 5
-    ```
+ 
+     ```bash
+     kaggle b t push my-task -f benchmark.py --wait 60 --poll-interval 5
+     ```
+ 
+4.  Push a task with Kaggle datasets attached:
+ 
+     ```bash
+     kaggle b t push my-task -f benchmark.py -d kaggle/titanic -d user/my-dataset
+     ```
+ 
+5.  Push a task with datasets and wait:
+ 
+     ```bash
+     kaggle b t push my-task -f benchmark.py --wait -d kaggle/titanic
+     ```
 
 **Purpose:**
 
 This command reads a `.py` file, converts it to a Jupyter notebook format, and uploads it to Kaggle as a benchmark task. If a task with the same slug already exists, a new version is created. The file is validated to ensure it contains a `@task` decorator matching the given task name.
+ 
+**Note on dataset attachment:** When `--kaggle-dataset` / `-d` is specified, the listed datasets are attached to the task's underlying notebook kernel. During execution, they are accessible at `/kaggle/input/<dataset-slug>/` by default, falling back to `/kaggle/input/<owner>/<dataset-slug>/` in the event of a naming conflict. If you re-push without `-d`, all previously-attached datasets are detached (a warning is printed). To preserve datasets across pushes, re-specify them each time. If any specified dataset is invalid, non-existent, or inaccessible, the push command will **fail** with an error: `Failed to push task: Failed to attach the following data sources (not found or inaccessible): <dataset>`.
 
 ---
 
@@ -148,13 +165,14 @@ kaggle benchmarks tasks run <TASK> [options]
 
 **Arguments:**
 
-*   `<TASK>`: Task name (slug).
+*   `<TASK>`: Task name (slug, e.g. `my-task`).
 
 **Options:**
 
-*   `-m, --model <MODEL> [MODEL ...]`: One or more model slugs to run against. If omitted, an interactive model picker is displayed.
+*   `-m, --model <MODEL>`: Model slug (e.g. `gemini-2.5-pro`) to run against. Repeat for multiple models (e.g. `-m gemini-2.5-pro -m claude-sonnet-4`). If omitted, an interactive model picker is displayed.
 *   `--wait [TIMEOUT]`: Wait for runs to complete. Optionally specify a timeout in seconds (`0` or omit value = wait indefinitely).
-*   `--poll-interval <SECONDS>`: Seconds between status polls when using `--wait` (default: `10`).
+*   `--poll-interval <SECONDS>`: Maximum seconds between status polls (default: `60`). Polling starts at 5s and increases by 50% each iteration until reaching this value.
+*   `-v, --verbose`: Enable verbose polling logs.
 
 **Examples:**
 
@@ -167,13 +185,13 @@ kaggle benchmarks tasks run <TASK> [options]
 2.  Run a task against specific models:
 
     ```bash
-    kaggle b t run my-task -m google/gemini-2.5-pro anthropic/claude-sonnet-4
+    kaggle b t run my-task -m gemini-2.5-pro -m claude-sonnet-4
     ```
 
 3.  Run a task and wait for all runs to finish:
 
     ```bash
-    kaggle b t run my-task -m google/gemini-2.5-pro --wait
+    kaggle b t run my-task -m gemini-2.5-pro --wait
     ```
 
 **Purpose:**
@@ -229,11 +247,11 @@ kaggle benchmarks tasks status <TASK> [options]
 
 **Arguments:**
 
-*   `<TASK>`: Task name (slug).
+*   `<TASK>`: Task name (slug, e.g. `my-task`).
 
 **Options:**
 
-*   `-m, --model <MODEL> [MODEL ...]`: Filter the run table to specific model slug(s).
+*   `-m, --model <MODEL>`: Filter the run table to a specific model slug (e.g. `gemini-2.5-pro`). Repeat for multiple models.
 
 **Examples:**
 
@@ -246,7 +264,7 @@ kaggle benchmarks tasks status <TASK> [options]
 2.  Show status for specific models only:
 
     ```bash
-    kaggle b t status my-task -m google/gemini-2.5-pro
+    kaggle b t status my-task -m gemini-2.5-pro
     ```
 
 **Purpose:**
@@ -267,12 +285,14 @@ kaggle benchmarks tasks download <TASK> [options]
 
 **Arguments:**
 
-*   `<TASK>`: Task name (slug).
+*   `<TASK>`: Task name (slug, e.g. `my-task`).
 
 **Options:**
 
-*   `-m, --model <MODEL> [MODEL ...]`: Download outputs only for specific model slug(s).
+*   `-m, --model <MODEL>`: Download outputs only for a specific model slug (e.g. `gemini-2.5-pro`). Repeat for multiple models.
 *   `-o, --output <DIRECTORY>`: Directory to download output files into (defaults to current working directory).
+*   `-s, --include-source`: Also download the kernel session's source notebooks.
+*   `-f, --force`: Force re-download of already completed runs, overwriting local files.
 
 **Examples:**
 
@@ -285,7 +305,19 @@ kaggle benchmarks tasks download <TASK> [options]
 2.  Download outputs for a specific model into a custom directory:
 
     ```bash
-    kaggle b t download my-task -m google/gemini-2.5-pro -o ./results
+    kaggle b t download my-task -m gemini-2.5-pro -o ./results
+    ```
+
+3.  Download outputs with source notebooks included:
+
+    ```bash
+    kaggle b t download my-task --include-source
+    ```
+
+4.  Force re-download of previously downloaded runs:
+
+    ```bash
+    kaggle b t download my-task --force
     ```
 
 **Purpose:**
@@ -297,7 +329,97 @@ Downloads and extracts the output zip archive for each completed run. Files are
    ├── output files...
 ```
 
-Already-downloaded runs (where the output directory exists) are automatically skipped.
+Already-downloaded runs (where the output directory exists) are automatically skipped unless the `-f` / `--force` flag is used, in which case they are overwritten.
+
+When `--include-source` is used, the downloaded zip also contains the kernel session's source files (e.g., `__notebook__.ipynb` and `__notebook_source__.ipynb`).
+
+---
+
+### `kaggle benchmarks tasks log`
+
+Get execution logs for benchmark task run(s).
+
+**Usage:**
+
+```bash
+kaggle benchmarks tasks log <TASK> [options]
+```
+
+**Arguments:**
+
+*   `<TASK>`: Task name (slug, e.g. `my-task`).
+
+**Options:**
+
+*   `-m, --model <MODEL>`: Filter logs to a specific model slug (e.g. `gemini-2.5-pro`). Repeat for multiple models. If omitted, logs for all runs are shown.
+
+**Aliases:** `log`, `logs`
+
+**Examples:**
+
+1.  Show logs for all runs of a task:
+
+    ```bash
+    kaggle b t log my-task
+    ```
+
+2.  Show logs for a specific model's run(s):
+
+    ```bash
+    kaggle b t log my-task -m gemini-2.5-pro
+    ```
+
+3.  Show logs for multiple models:
+
+    ```bash
+    kaggle b t logs my-task -m gemini-2.5-pro -m claude-sonnet-4
+    ```
+
+**Purpose:**
+
+Fetches and displays execution logs for benchmark task runs. Each run's logs are printed with a structured header and footer for clear identification:
+
+```
+═══ Logs for gemini-2.5-pro (Run 123) [COMPLETED] ═══
+<log output>
+═══ (42 lines) ═══
+
+═══ Logs for claude-sonnet-4 (Run 456) [ERRORED] ═══
+<log output>
+═══ (18 lines) ═══
+
+Showed logs for 2 run(s) across 2 model(s).
+```
+
+*   **Header**: Shows model name, run ID, and run state (`COMPLETED`, `ERRORED`, `RUNNING`, etc.).
+*   **Footer**: Shows the line count for each run's log output.
+*   **Summary**: Printed at the end with total run and model counts.
+
+The command handles two response types from the server:
+
+*   **Active runs**: Logs are streamed in real-time via Server-Sent Events (SSE).
+*   **Completed runs**: The persisted log file is returned and printed.
+
+### Concurrency & Streaming Order
+
+When viewing logs for multiple concurrent model runs, the CLI processes and outputs them **sequentially** to prevent logs from interleaving and garbling your terminal output:
+1. The CLI prints the header for the first model run in the queue.
+2. If that run is currently active, the CLI blocks and streams its log output in real-time via SSE until it completes.
+3. The log output for the next model run will **only** be printed once the previous model run's log stream finishes and closes.
+4. Any model runs that complete in the background while you are watching the first stream will print instantly as completed persisted logs once their turn in the sequence is reached.
+
+### Model Slug Normalization
+
+Benchmark model names are automatically normalized on both input and output. This makes it easy to pass various formats interchangeably while keeping displays and directories clean.
+
+*   **Flexible Inputs**: The CLI accepts model names in several formats:
+    *   **Canonical Slugs (recommended)**: `gemini-2.5-pro` or `claude-sonnet-4`
+    *   **With Provider Prefix**: `google/gemini-2.5-pro` or `anthropic/claude-sonnet-4`
+    *   **With Version/Proxy `@` symbols**: `anthropic/claude-haiku-4-5@20251001` or `claude-sonnet-4-6@default`
+*   **Unified Normalization**: The client automatically strips any provider prefix (e.g., `google/` or `anthropic/`) and replaces `@` characters with `-` to match the server's canonical database slug format.
+*   **Clean Outputs**:
+    *   **Status Display**: Tables and error logs display the canonical, hyphenated slugs (e.g., `claude-haiku-4-5-20251001` and `gemini-2.0-flash-lite-001`) for readability.
+    *   **Hierarchical Downloads**: Run outputs are extracted into clean folders using the canonical slugs (e.g., `./<task>/<version>/claude-haiku-4-5-20251001/<run_id>/`), with no `@` or `/` symbols in folder names.
 
 ---
 
@@ -335,7 +457,7 @@ kaggle benchmarks tasks delete <TASK> [options]
 
 **Arguments:**
 
-*   `<TASK>`: Task name (slug).
+*   `<TASK>`: Task name (slug, e.g. `my-task`).
 
 **Options:**
 
@@ -350,15 +472,53 @@ kaggle b t delete my-task -y
 **Purpose:**
 
 Deletes a benchmark task and all associated runs. **Note:** This command is not yet supported by the server.
+ 
+---
+ 
+### `kaggle benchmarks tasks publish`
+ 
+Publishes a benchmark task, making it publicly visible. By default, the backing notebook is also published.
+ 
+**Usage:**
+ 
+```bash
+kaggle benchmarks tasks publish <TASK> [options]
+```
+ 
+**Arguments:**
+ 
+*   `<TASK>`: Task name (slug, e.g. `my-task`).
+ 
+**Options:**
+ 
+*   `--no-publish-backing-notebook`: Do not publish the backing notebook (it is published by default).
+ 
+**Examples:**
+ 
+1.  Publish a task and its backing notebook (default):
+ 
+    ```bash
+    kaggle b t publish my-task
+    ```
+ 
+2.  Publish a task without its backing notebook:
+ 
+    ```bash
+    kaggle b t publish my-task --no-publish-backing-notebook
+    ```
+ 
+**Purpose:**
+ 
+This command changes the task's visibility from private to public. By default, the backing notebook (the kernel associated with the task) is also published. Use `--no-publish-backing-notebook` to publish only the task metadata. Publishing is idempotent — re-publishing an already-public task prints a message and returns successfully. Unpublishing is not supported through this command.
 
-## `kaggle benchmarks topics`
+## `kaggle benchmarks topics list`
 
 Lists discussion topics for a benchmark.
 
 **Usage:**
 
 ```bash
-kaggle benchmarks topics <BENCHMARK> [options]
+kaggle benchmarks topics list <BENCHMARK> [options]
 ```
 
 **Arguments:**
@@ -368,16 +528,16 @@ kaggle benchmarks topics <BENCHMARK> [options]
 **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.
-*   `-s, --search <SEARCH_TERM>`: Search query.
 *   `-v, --csv`: Print results in CSV format.
 *   `-q, --quiet`: Suppress verbose output.
 
 **Example:**
 
 ```bash
-kaggle benchmarks topics kaggle/chess
+kaggle benchmarks topics list kaggle/chess
 ```
 
 **Purpose:**
@@ -391,22 +551,22 @@ Displays a benchmark discussion topic with all comments in tree form.
 **Usage:**
 
 ```bash
-kaggle benchmarks topics show <BENCHMARK>/<TOPIC_ID> [options]
+kaggle benchmarks topics show <TOPIC_REF> [options]
 ```
 
 **Arguments:**
 
 *   `<TOPIC_REF>`: A topic reference, which can be:
-    *   `<benchmark>/<topic-id>` (e.g., `kaggle/chess/614080`)
-    *   `<benchmark> <topic-id>` (two separate arguments)
+    *   `<benchmark>/<topic-id>` (e.g., `kaggle/chess/614080` - note that this supports multi-slash benchmark slugs)
+    *   `<benchmark> <topic-id>` (two separate arguments, where `<topic-id>` is passed as second argument)
     *   `<topic-id>` (bare numeric ID)
 
 **Options:**
 
-*   `-v, --csv`: Print results in CSV format.
-*   `-q, --quiet`: Suppress verbose output.
 *   `--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:**
 

{kaggle-2.1.2 → kaggle-2.2.0}/docs/competitions.md

@@ -224,24 +224,28 @@ kaggle competitions leaderboard <COMPETITION> [options]
 
 This command lets you view your ranking and the scores of other participants in a competition.
 
-## `kaggle competitions topics`
+## `kaggle competitions topics list`
 
 Lists discussion topics for a competition.
 
 **Usage:**
 
 ```bash
-kaggle competitions topics <COMPETITION> [options]
+kaggle competitions topics list [COMPETITION] [options]
 ```
 
+Note: `kaggle competitions topics` (without `list` subcommand) is supported as a shortcut to list topics for the default competition (configured via `kaggle config set competition`).
+
 **Arguments:**
 
-*   `<COMPETITION>`: Competition URL suffix (e.g., `titanic`).
+*   `[COMPETITION]`: Competition URL suffix (e.g., `titanic`). Optional if default competition is configured.
 
 **Options:**
 
-*   `--sort-by <SORT_BY>`: Sort order. Valid options: `hot`, `top`, `new`, `recent`, `active`, `relevance`.
-*   `-p, --page <PAGE>`: Page number (1-based).
+*   `-s, --sort-by <SORT_BY>`: Sort order. Valid options: `hot`, `top`, `new`, `recent`, `active`, `relevance`.
+*   `--search <SEARCH>`: Search query to filter topics.
+*   `--page-size <PAGE_SIZE>`: Number of items to show on a page. Default is 20, max is 200.
+*   `--page-token <PAGE_TOKEN>`: Page token for results paging.
 *   `-v, --csv`: Print results in CSV format.
 *   `-q, --quiet`: Suppress verbose output.
 
@@ -250,7 +254,7 @@ kaggle competitions topics <COMPETITION> [options]
 List discussion topics for the "titanic" competition sorted by most recent:
 
 ```bash
-kaggle competitions topics titanic --sort-by recent
+kaggle competitions topics list titanic -s recent
 ```
 
 **Purpose:**
@@ -264,22 +268,22 @@ Displays a competition discussion topic with all comments in tree form.
 **Usage:**
 
 ```bash
-kaggle competitions topics show <COMPETITION>/<TOPIC_ID> [options]
+kaggle competitions topics show <TOPIC_REF> [options]
 ```
 
 **Arguments:**
 
 *   `<TOPIC_REF>`: A topic reference, which can be:
     *   `<competition>/<topic-id>` (e.g., `titanic/12345`)
-    *   `<competition> <topic-id>` (two separate arguments)
+    *   `<competition> <topic-id>` (two separate arguments, where `<topic-id>` is passed as second argument)
     *   `<topic-id>` (bare numeric ID)
 
 **Options:**
 
-*   `-v, --csv`: Print results in CSV format.
-*   `-q, --quiet`: Suppress verbose output.
 *   `--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:**
 
@@ -291,7 +295,7 @@ kaggle competitions topics show titanic/12345
 
 **Purpose:**
 
-This command displays a full discussion topic along with all of its comments rendered in an indented tree structure. This replaces the older `topic-messages` command.
+This command displays a full discussion topic along with all of its comments rendered in an indented tree structure.
 
 ## `kaggle competitions topic-messages`
 

{kaggle-2.1.2 → kaggle-2.2.0}/docs/datasets.md

@@ -308,14 +308,14 @@ kaggle datasets delete username/dataset-slug --yes
 
 This command permanently removes one of your datasets from Kaggle. Use with caution.
 
-## `kaggle datasets topics`
+## `kaggle datasets topics list`
 
 Lists discussion topics for a dataset.
 
 **Usage:**
 
 ```bash
-kaggle datasets topics <DATASET> [options]
+kaggle datasets topics list <DATASET> [options]
 ```
 
 **Arguments:**
@@ -325,9 +325,9 @@ kaggle datasets topics <DATASET> [options]
 **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.
-*   `-s, --search <SEARCH_TERM>`: Search query.
 *   `-v, --csv`: Print results in CSV format.
 *   `-q, --quiet`: Suppress verbose output.
 
@@ -336,7 +336,7 @@ kaggle datasets topics <DATASET> [options]
 List recent topics for the zillow/zecon dataset:
 
 ```bash
-kaggle datasets topics zillow/zecon --sort-by recent
+kaggle datasets topics list zillow/zecon --sort-by recent
 ```
 
 **Purpose:**
@@ -350,22 +350,22 @@ Displays a dataset discussion topic with all comments in tree form.
 **Usage:**
 
 ```bash
-kaggle datasets topics show <DATASET>/<TOPIC_ID> [options]
+kaggle datasets topics show <TOPIC_REF> [options]
 ```
 
 **Arguments:**
 
 *   `<TOPIC_REF>`: A topic reference, which can be:
-    *   `<dataset>/<topic-id>` (e.g., `zillow/zecon/12345`)
-    *   `<dataset> <topic-id>` (two separate arguments)
+    *   `<dataset>/<topic-id>` (e.g., `zillow/zecon/12345` - note that this supports multi-slash dataset slugs)
+    *   `<dataset> <topic-id>` (two separate arguments, where `<topic-id>` is passed as second argument)
     *   `<topic-id>` (bare numeric ID)
 
 **Options:**
 
-*   `-v, --csv`: Print results in CSV format.
-*   `-q, --quiet`: Suppress verbose output.
 *   `--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:**
 

{kaggle-2.1.2 → kaggle-2.2.0}/docs/forums.md

@@ -6,7 +6,7 @@ Commands for browsing and reading Kaggle discussion forums.
 
 Lists all discussion forums. Also available as `kaggle forums list`.
 
-**Alias:** `fo`
+**Alias:** `f`
 
 **Usage:**
 
@@ -31,28 +31,30 @@ kaggle forums -v
 
 This command helps you discover all available discussion forums on Kaggle.
 
-## `kaggle forums topics`
+## `kaggle forums topics list`
 
 Lists discussion topics in a forum.
 
 **Usage:**
 
 ```bash
-kaggle forums topics <FORUM> [options]
+kaggle forums topics list [FORUM] [options]
 ```
 
+Note: `kaggle forums topics` (without `list` subcommand) is supported as a shortcut to list all topics (without forum filtering).
+
 **Arguments:**
 
-*   `<FORUM>`: Forum slug (e.g., `getting-started`, `product-feedback`).
+*   `[FORUM]`: Forum slug (e.g., `1`, `product-feedback`). Optional.
 
 **Options:**
 
 *   `--sort-by <SORT_BY>`: Sort order. Valid options: `hot`, `top`, `new`, `recent`, `active`, `relevance`.
-*   `--page-size <PAGE_SIZE>`: Number of items per page.
-*   `--page-token <PAGE_TOKEN>`: Page token for pagination.
-*   `-s, --search <SEARCH_TERM>`: Search query.
+*   `-s, --search <SEARCH_TERM>`: Search query to filter topics.
 *   `--category <CATEGORY>`: Filter by category. Valid options: `all`, `forums`, `competitions`, `datasets`, `competition_write_ups`, `models`, `benchmarks`.
 *   `--group <GROUP>`: Filter by group. Valid options: `all`, `owned`, `upvoted`, `bookmarked`, `my_activity`, `drafts`.
+*   `--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.
 
@@ -61,7 +63,7 @@ kaggle forums topics <FORUM> [options]
 List topics in the "getting-started" forum sorted by most recent, showing 5 per page:
 
 ```bash
-kaggle forums topics getting-started --sort-by recent --page-size 5
+kaggle forums topics list getting-started --sort-by recent --page-size 5
 ```
 
 **Purpose:**
@@ -82,15 +84,15 @@ kaggle forums topics show <TOPIC_REF> [options]
 
 *   `<TOPIC_REF>`: A topic reference, which can be:
     *   `<forum-name>/<topic-id>` (e.g., `getting-started/12345`)
-    *   `<forum-name> <topic-id>` (two separate arguments)
+    *   `<forum-name> <topic-id>` (two separate arguments, where `<topic-id>` is passed as second argument)
     *   `<topic-id>` (bare numeric ID)
 
 **Options:**
 
-*   `-v, --csv`: Print results in CSV format.
-*   `-q, --quiet`: Suppress verbose output.
 *   `--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:**