feat(search): add unified search command across Kaggle content

CHANGELOG.md

@@ -3,6 +3,7 @@ Changelog
 
 ### Next
 
+* Add unified `kaggle search` command across competitions, datasets, notebooks, models, users, and discussions
 * Add `--wait`/`--poll-interval` to `kaggle competitions submit` to wait for scoring, and add `kaggle competitions submission <ref>` to look up a single submission's status and score
 
 ### 2.2.4

docs/index.rst

@@ -22,4 +22,5 @@ kaggle-cli documentation
    model_instances
    model_instances_versions
    benchmarks
+   search
    tutorials

docs/search.md

@@ -0,0 +1,76 @@
+# Search Command
+
+Search across all Kaggle content from a single command.
+
+## `kaggle search`
+
+Runs a unified search over Kaggle competitions, datasets, notebooks, models,
+users, and discussions and returns one ranked list of results. This is the
+cross-content equivalent of the per-command `-s/--search` flags (such as
+`kaggle datasets list --search`); use it when you don't yet know which content
+type you're looking for, or when you want results from several types at once.
+
+By default, `kaggle search` searches all CLI-supported content types
+(competition, dataset, notebook, model, user, discussion, benchmark) — not every
+backend document type (it excludes types the CLI cannot render usefully, such as
+comments, blogs, and courses). Result ordering uses the backend's canonical
+cross-content ranking. Use `--type` to narrow to specific types.
+
+**Usage:**
+
+```bash
+kaggle search "<query>" [options]
+```
+
+**Options:**
+
+*   `query`: The term(s) to search for (required).
+*   `-t, --type <TYPES>`: Restrict results to a comma-separated list of content types. Valid types: `competition`, `dataset`, `notebook`, `model`, `user`, `discussion`, `benchmark`. If omitted, all of these CLI-supported types are searched.
+*   `-m, --mine`: Restrict the search to your own content.
+*   `--sort-by <SORT_BY>`: Sort order. One of: `relevance` (default), `hotness`, `votes`, `dateCreated`, `dateUpdated`, `totalComments`, `lastViewed`.
+*   `--page-size <SIZE>`: Number of results to show on a page (default: 20, max: 100).
+*   `--page-token <TOKEN>`: Page token for results paging (printed as `Next Page Token = ...` at the top of a page when more results exist).
+*   `-v, --csv`: Print results in CSV format instead of a table.
+*   `--format <FORMAT>`: Print results in the selected format (`csv`, `table`, `json`). Supports field projection, e.g. `--format 'json(type,ref)'`.
+
+**Result columns:** `type`, `ref`, `title`, `owner`, `votes`. The `ref` column
+is the identifier you can pass to other commands — `owner/slug` for datasets,
+notebooks, and models; the bare slug for competitions and users.
+
+**Examples:**
+
+1.  Search everything for a term:
+
+    ```bash
+    kaggle search "protein folding"
+    ```
+
+2.  Search only datasets and models:
+
+    ```bash
+    kaggle search "diffusion" --type dataset,model
+    ```
+
+3.  Find users:
+
+    ```bash
+    kaggle search "andrew ng" --type user
+    ```
+
+4.  Search your own content, most recently updated first:
+
+    ```bash
+    kaggle search "baseline" --mine --sort-by dateUpdated
+    ```
+
+5.  Get machine-readable output:
+
+    ```bash
+    kaggle search "titanic" --format json
+    ```
+
+6.  Fetch the next page:
+
+    ```bash
+    kaggle search "llm" --page-size 50 --page-token <TOKEN>
+    ```

skills/SKILL.md

@@ -59,7 +59,8 @@ kaggle
 │   └── topics {list, show}
 ├── config {view, set, unset}
 ├── auth {login, print-access-token, revoke}
-└── quota
+├── quota
+└── search
 ```
 
 Note: the CLI accepts aliases such as `kernels get` for `kernels pull` and
@@ -83,6 +84,7 @@ Read only the reference needed for the user's task:
 - [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.
+- [Search](references/search.md) - unified cross-content search over competitions, datasets, notebooks, models, users, and discussions.
 
 ## Operating Guidance
 

skills/references/search.md

@@ -0,0 +1,65 @@
+# Search CLI Reference
+
+Use `kaggle search` to run a unified search across Kaggle competitions,
+datasets, notebooks, models, users, and discussions from a single command.
+
+## Prerequisites
+
+- Python 3.11+ with the `kaggle` package installed.
+- Kaggle credentials.
+
+## Command Hierarchy
+
+```text
+kaggle search "<query>"
+```
+
+## `kaggle search`
+
+Searches across Kaggle content types and returns one ranked result list.
+Unlike the per-command `-s/--search` flags (for example
+`kaggle datasets list --search`), this command searches multiple content types
+in a single request and can also find users and discussions.
+
+By default it searches all CLI-supported content types (competition, dataset,
+notebook, model, user, discussion, benchmark) — not every backend document type;
+types the CLI cannot render usefully (comments, blogs, courses, etc.) are
+excluded. Ordering uses the backend's canonical cross-content ranking.
+
+**Usage:**
+
+```bash
+kaggle search "<query>" [options]
+```
+
+**Options:**
+
+- `query`: Term(s) to search for (required).
+- `-t, --type <TYPES>`: Comma-separated content types to restrict to. Valid: `competition`, `dataset`, `notebook`, `model`, `user`, `discussion`, `benchmark`. Omit to search all of these CLI-supported types.
+- `-m, --mine`: Restrict the search to your own content.
+- `--sort-by <SORT_BY>`: One of `relevance` (default), `hotness`, `votes`, `dateCreated`, `dateUpdated`, `totalComments`, `lastViewed`.
+- `--page-size <SIZE>`: Results per page (default 20, max 100).
+- `--page-token <TOKEN>`: Page token for paging.
+- `-v, --csv`: Print CSV instead of a table.
+- `--format <FORMAT>`: `csv`, `table`, or `json`; supports projection, e.g. `--format 'json(type,ref)'`.
+
+**Examples:**
+
+```bash
+kaggle search "weather"
+kaggle search "diffusion" --type dataset,model
+kaggle search "andrew ng" --type user
+kaggle search "baseline" --mine --sort-by dateUpdated
+kaggle search "titanic" --format json
+```
+
+**Purpose:** Discover content across the whole platform when you don't know the
+content type in advance, or when you want results from several types at once.
+
+## Output
+
+Results are a table with columns `type`, `ref`, `title`, `owner`, and `votes`.
+The `ref` value is reusable with other commands: `owner/slug` for datasets,
+notebooks, and models; the bare slug for competitions and users. For example,
+a `dataset` result's `ref` can be passed to `kaggle datasets download`, and a
+`competition` result's `ref` to `kaggle competitions files`.