### Benchmarks # Benchmarks Commands Commands for interacting with Kaggle Benchmarks. Benchmarks let you define evaluation tasks as Python scripts, run them against one or more LLM models via the Kaggle Model Proxy, and download the results. The top-level command is `kaggle benchmarks` (alias: `kaggle b`), which has the following subcommands and groups: * **`auth`** — Fetch Model Proxy credentials. * **`init`** — Fetch credentials and default environment variables for local development. * **`quota`** — Show your Model Proxy (AI inference) spend quota. * **`leaderboard`** — Get benchmark leaderboard information. * **`tasks`** (alias: `t`) — Manage benchmark tasks (push, run, list, status, download, log, models, delete, publish). * **`topics`** — Browse discussion topics for a benchmark. ## `kaggle benchmarks auth` Fetches a Model Proxy token and persists the credential environment variables to a file. **Usage:** ```bash kaggle benchmarks auth [options] ``` **Options:** * `-y, --yes`: Automatically confirm without prompting. * `--env-file `: File to write environment variables to (default: `.env`). **Example:** Write Model Proxy credentials to the default `.env` file, confirming automatically: ```bash kaggle b auth -y ``` **Purpose:** This command fetches a short-lived Model Proxy API key and URL from Kaggle and appends them to your environment file. The variables written are: * `MODEL_PROXY_URL` * `MODEL_PROXY_API_KEY` * `MODEL_PROXY_EXPIRY_TIME` ## `kaggle benchmarks init` Fetches Model Proxy credentials **and** additional default environment variables useful for local benchmark development. Also generates a starter example task file and a syntax reference document. **Usage:** ```bash kaggle benchmarks init [options] ``` **Options:** * `-y, --yes`: Automatically confirm without prompting. * `--env-file `: File to write environment variables to (default: `.env`). * `--example-file `: File to write the example benchmark task to (default: `example_task.py`). **Examples:** 1. Initialize with defaults (writes `.env`, `example_task.py`, and `kaggle_benchmarks_reference.md`): ```bash kaggle b init -y ``` 2. Initialize with a custom env file and example file: ```bash kaggle b init -y --env-file my_project/.env --example-file my_project/my_task.py ``` **Purpose:** In addition to the three credential variables written by `auth`, `init` also writes: * `LLM_DEFAULT` — Default model slug for tasks. * `LLM_DEFAULT_EVAL` — Default model slug for evaluation. * `LLMS_AVAILABLE` — Comma-separated list of available model slugs. > [!WARNING] > `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 minted for local development **is** 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. * **`kaggle_benchmarks_reference.md`** — A syntax reference document for the `kaggle-benchmarks` task API. If either file already exists, it is skipped without overwriting. --- ## `kaggle benchmarks quota` Shows your current Model Proxy (AI inference) spend quota, one row per refill period. **Usage:** ```bash kaggle benchmarks quota [options] ``` **Options:** * `-v, --csv`: Print results in CSV format. * `--format `: Print results in the selected format (`csv`, `table`, `json`). **Example:** ```bash $ kaggle b quota period used remaining total refillAt ------- ------ --------- ------- ------------------------- Daily $1.20 $3.80 $5.00 2026-08-08T00:00:00+00:00 Monthly $14.50 $85.50 $100.00 2026-09-01T00:00:00+00:00 ``` **Purpose:** Amounts are in USD and reflect inference spend through the Model Proxy — this is separate from the top-level `kaggle quota` command, which reports weekly GPU and TPU accelerator *hours*. `remaining` is derived as `total - used` and is clamped at `$0.00`, so an overage shows as zero remaining rather than a negative balance. --- ## `kaggle benchmarks leaderboard` Get benchmark leaderboard information. **Usage:** ```bash kaggle benchmarks leaderboard [options] ``` **Arguments:** * ``: Benchmark slug (e.g., `owner/benchmark-slug`). **Options:** * `--version `: Benchmark version (optional). * `-s, --show`: Show the leaderboard in the terminal. * `-d, --download`: Download the leaderboard as a CSV file. * `-p, --path `: Folder where the leaderboard will be downloaded (defaults to current working directory). * `-v, --csv`: Print results in CSV format (when used with `--show`). * `--format `: Print results in a specific format (e.g., `json`). **Examples:** 1. Show the leaderboard for a benchmark: ```bash kaggle b leaderboard owner/my-benchmark --show ``` 2. Download the leaderboard as CSV: ```bash kaggle b leaderboard owner/my-benchmark --download ``` 3. Show a specific version of the leaderboard in JSON format: ```bash kaggle b leaderboard owner/my-benchmark --version 2 --show --format json ``` **Purpose:** Displays or downloads the evaluation results for all models that have run tasks in the specified benchmark. The leaderboard is represented as a table where rows are model versions and columns are benchmark tasks, showing the score achieved by each model on each task. --- ## Tasks Commands All tasks commands live under `kaggle benchmarks tasks` (alias: `kaggle b t`). ### Task Name Format Task arguments (``) support two formats: * **Bare slug** (`my-task`): Refers to a task owned by the current user. * **Owner prefix** (`owner/my-task`): Refers to a specific owner's task (e.g., another user's public task, or `your-username/my-task`). | Command Group | Supported Formats | Description | |---|---|---| | **View & Run** (`run`, `status`, `download`, `log`) | `my-task`, `owner/my-task` | Interact with your own tasks or public tasks from other users | | **Publish** (`publish`) | `my-task`, `your-username/my-task` | Make your own task public (must be task owner) | | **Create** (`push`) | `my-task` only | Must match the `@task(name="...")` decorator in your Python source file | > **Slug Normalization:** Task names are automatically converted to URL-safe slugs (`My Task` → `my-task`). For `owner/task` arguments, each segment is slugified independently (`Owner/My Task` → `owner/my-task`) so the `/` separator is preserved. ### `kaggle benchmarks tasks push` Creates or updates a benchmark task from a local Python source file. The file must contain at least one function decorated with `@task`. **Usage:** ```bash kaggle benchmarks tasks push -f [options] ``` **Arguments:** * ``: Task name. Automatically normalized to a URL-safe slug (e.g., `my_task` or `My Task` becomes `my-task`). **Options:** * `-f, --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 `: 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 `: 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//` by default. If a naming conflict occurs, the fully qualified mount path `/kaggle/input///` is used instead. **Examples:** 1. Push a task and return immediately: ```bash kaggle b t push my-task -f benchmark.py ``` 2. Push a task and wait for creation to finish: ```bash kaggle b t push my-task -f benchmark.py --wait ``` 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 ``` 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//` by default, falling back to `/kaggle/input///` 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): `. --- ### `kaggle benchmarks tasks run` Runs a previously pushed task against one or more models. **Usage:** ```bash kaggle benchmarks tasks run [options] ``` **Arguments:** * ``: Task name (slug, e.g. `my-task` or `owner/my-task`). **Options:** * `-m, --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 `: 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:** 1. Run a task with interactive model selection: ```bash kaggle b t run my-task ``` 2. Run a task against specific models: ```bash 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 gemini-2.5-pro --wait ``` **Purpose:** This command schedules benchmark runs on the server. The task must be in a `COMPLETED` creation state before it can be run. If no models are specified, the CLI presents a paginated list of available models for interactive selection. --- ### `kaggle benchmarks tasks list` Lists benchmark tasks owned by the current user. **Usage:** ```bash kaggle benchmarks tasks list [options] ``` **Options:** * `--name-regex `: Filter task names by regular expression. * `--status `: Filter tasks by creation status. Valid values: `queued`, `running`, `completed`, `errored`. **Examples:** 1. List all your tasks: ```bash kaggle b t list ``` 2. List only completed tasks whose names contain "gemini": ```bash kaggle b t list --name-regex gemini --status completed ``` **Purpose:** Displays a table of your benchmark tasks showing the task slug, current version (or `unset` if unavailable), creation status, and creation timestamp. --- ### `kaggle benchmarks tasks status` Shows task details and per-model run status. **Usage:** ```bash kaggle benchmarks tasks status [options] ``` **Arguments:** * ``: Task name (slug, e.g. `my-task` or `owner/my-task`). **Options:** * `-m, --model `: Filter the run table to a specific model slug (e.g. `gemini-2.5-pro`). Repeat for multiple models. **Examples:** 1. Show full status for a task: ```bash kaggle b t status my-task ``` 2. Show status for another user's task: ```bash kaggle b t status someuser/their-task ``` 3. Show status for specific models only: ```bash kaggle b t status my-task -m gemini-2.5-pro ``` **Purpose:** 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` Downloads output files for completed benchmark runs. **Usage:** ```bash kaggle benchmarks tasks download [options] ``` **Arguments:** * ``: Task name (slug, e.g. `my-task` or `owner/my-task`). **Options:** * `-m, --model `: Download outputs only for a specific model slug (e.g. `gemini-2.5-pro`). Repeat for multiple models. * `-o, --output `: 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:** 1. Download all completed run outputs for a task: ```bash kaggle b t download my-task ``` 2. Download outputs from another user's public task: ```bash kaggle b t download someuser/their-task ``` 3. Download outputs for a specific model into a custom directory: ```bash kaggle b t download my-task -m gemini-2.5-pro -o ./results ``` 4. Download outputs with source notebooks included: ```bash kaggle b t download my-task --include-source ``` 5. Force re-download of previously downloaded runs: ```bash kaggle b t download my-task --force ``` **Purpose:** Downloads and extracts the output zip archive for each completed run. Files are organized in a hierarchical layout that includes the task's version number (or `unset` if unavailable): ``` ///// ├── output files... ``` Progress is rendered as a table with one row per run: ``` Model File Size Progress ──────────────────── ──────────────────────────────────────── ────────── ────────── gemini-2.5-pro gemini-2.5-pro/12345/ 1.24MB Done claude-sonnet-4 claude-sonnet-4/12346/ 2.10MB Cached ``` The `Size` column reports the extracted on-disk size of the run's output directory. The `Progress` column is one of `Done` (freshly downloaded), `Cached` (output directory already on disk from a previous download), or `Bad zip` (downloaded archive was corrupt). Already-downloaded runs (where the output directory exists) are automatically skipped — they appear as `Cached` rows — 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`). If you re-run with `-s` after a previous download that omitted source notebooks, the cached directories are not re-fetched and the `-s` flag is effectively ignored. The CLI detects this and prints a tip after the summary: ``` Tip: 2 cached run(s) lack source notebooks. Re-run with -f -s to fetch them. ``` Use `-f -s` together to force re-download and backfill the source notebooks into the cached runs. --- ### `kaggle benchmarks tasks log` Get execution logs for benchmark task run(s). **Usage:** ```bash kaggle benchmarks tasks log [options] ``` **Arguments:** * ``: Task name (slug, e.g. `my-task` or `owner/my-task`). **Options:** * `-m, --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 another user's task: ```bash kaggle b t log someuser/their-task ``` 3. Show logs for a specific model's run(s): ```bash kaggle b t log my-task -m gemini-2.5-pro ``` 4. 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] ═══ ═══ (42 lines) ═══ ═══ Logs for claude-sonnet-4 (Run 456) [ERRORED] ═══ ═══ (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., `.///claude-haiku-4-5-20251001//`), with no `@` or `/` symbols in folder names. --- ### `kaggle benchmarks tasks models` Lists all available benchmark models. **Usage:** ```bash kaggle benchmarks tasks models ``` **Example:** ```bash kaggle b t models ``` **Purpose:** Prints a table of all models available for benchmark runs, showing each model's slug and display name. This is useful for discovering valid model slugs to pass to `run`, `status`, or `download` commands. --- ### `kaggle benchmarks tasks delete` Removes a benchmark task. **Usage:** ```bash kaggle benchmarks tasks delete [options] ``` **Arguments:** * ``: Task name (slug, e.g. `my-task` or `owner/my-task`). **Options:** * `-y, --yes`: Automatically confirm deletion without prompting. **Example:** ```bash 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 [options] ``` **Arguments:** * ``: Task name (slug, e.g. `my-task` or `owner/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 list` Lists discussion topics for a benchmark. **Usage:** ```bash kaggle benchmarks topics list [options] ``` **Arguments:** * ``: Benchmark slug (e.g., `kaggle/chess`). **Options:** * `--sort-by `: Sort order. Valid options: `hot`, `top`, `new`, `recent`, `active`, `relevance`. * `-s, --search `: Search query to filter topics. * `--page-size `: Number of items per page. * `--page-token `: Page token for pagination. * `-v, --csv`: Print results in CSV format. * `-q, --quiet`: Suppress verbose output. **Example:** ```bash kaggle benchmarks topics list kaggle/chess ``` **Purpose:** This command lets you browse discussion topics for a specific benchmark. ## `kaggle benchmarks topics show` Displays a benchmark discussion topic with all comments in tree form. **Usage:** ```bash kaggle benchmarks topics show [options] ``` **Arguments:** * ``: A topic reference, which can be: * `/` (e.g., `kaggle/chess/614080` - note that this supports multi-slash benchmark slugs) * ` ` (two separate arguments, where `` is passed as second argument) * `` (bare numeric ID) **Options:** * `--page-size `: Number of comments to show per page. * `--page-token `: Page token for comment pagination. * `-v, --csv`: Print results in CSV format. * `-q, --quiet`: Suppress verbose output. **Example:** ```bash kaggle benchmarks topics show kaggle/chess/614080 ``` **Purpose:** This command displays a full discussion topic along with all of its comments rendered in an indented tree structure. --- ### Competition Creation # Hosting a Competition from the CLI This page documents the host-facing commands added in kaggle-cli for the new public competition-creation API endpoints (kagglesdk 0.1.31+): - [`kaggle competitions init`](#kaggle-competitions-init) - [`kaggle competitions create`](#kaggle-competitions-create) - [`kaggle competitions pages create`](#kaggle-competitions-pages-create) - [`kaggle competitions hosts`](#kaggle-competitions-hosts) - [`kaggle competitions host-add`](#kaggle-competitions-host-add) - [`kaggle competitions settings get`](#kaggle-competitions-settings-get) - [`kaggle competitions settings update`](#kaggle-competitions-settings-update) - [`kaggle competitions data update`](#kaggle-competitions-data-update) - [`kaggle competitions solution create`](#kaggle-competitions-solution-create) - [`kaggle competitions solution status`](#kaggle-competitions-solution-status) - [`kaggle competitions launch`](#kaggle-competitions-launch) All of these commands require an authenticated session (`kaggle config set username/password` or an API token). A typical end-to-end host workflow looks like: ```bash # 1. Scaffold a metadata file. kaggle competitions init ./my-comp # 2. Edit ./my-comp/competition-metadata.json (fill in the INSERT_* placeholders). # 3. Create the (unlaunched) competition. kaggle competitions create -p ./my-comp # → Competition created: https://www.kaggle.com/competitions/my-comp-slug # 4. Author the description and rules pages. kaggle competitions pages create my-comp-slug --name description -f ./description.md --publish kaggle competitions pages create my-comp-slug --name rules -f ./rules.md --publish # 5. Update the competition data (train.csv, test.csv, sample_submission.csv, ...). kaggle competitions data update my-comp-slug -p ./data -m "Initial release" # 6. Upload the private solution CSV, then poll until scoring is ready. kaggle competitions solution create my-comp-slug -p ./solution.csv kaggle competitions solution status my-comp-slug # → Ready: true # 7. Optionally tune host-only settings not covered by competition-metadata.json # (deadlines, runtime caps, leaderboard behavior, etc.). kaggle competitions settings get my-comp-slug kaggle competitions settings update my-comp-slug -f ./settings.json # 8. Launch the competition (now, or schedule a future UTC time). kaggle competitions launch my-comp-slug --at 2027-01-01T00:00:00Z ``` These commands are independent — for example, you can call `pages create` on a competition that already exists, or use `launch` on a competition created via the host wizard. --- ## `kaggle competitions init` Writes a `competition-metadata.json` template into a folder. **Usage:** ```bash kaggle competitions init [folder] ``` **Arguments:** - `folder` (optional): Where to write `competition-metadata.json`. Defaults to the current directory. **Example:** ```bash kaggle competitions init ./my-comp ``` The generated file: ```json { "title": "INSERT_TITLE_HERE", "slug": "INSERT_SLUG_HERE", "briefDescription": "INSERT_BRIEF_DESCRIPTION_HERE", "privacy": "PUBLIC", "disableKernels": false, "hackathon": false, "cloneCompetitionId": null, "cloneExcludeCompetitionData": null, "clonePageNames": null, "licenseId": null, "organizationId": null, "numPrizes": null, "restrictLinkToEmailList": null, "reward": null } ``` See [Metadata reference](#competition-metadata-reference) below for what each field means. --- ## `kaggle competitions create` Creates a new competition from `competition-metadata.json`. The competition is created in an unlaunched (staged) state — use [`kaggle competitions launch`](#kaggle-competitions-launch) to publish it. **Usage:** ```bash kaggle competitions create [-p folder] ``` **Options:** - `-p, --path `: Folder containing `competition-metadata.json`. Defaults to the current directory. **Example:** ```bash kaggle competitions create -p ./my-comp # → Competition created: https://www.kaggle.com/competitions/my-comp-slug ``` **Errors you might see:** - `Default title detected, please update competition-metadata.json before creating` — you forgot to replace one of the `INSERT_*_HERE` placeholders. - `Invalid privacy '...'` — `privacy` must be one of `PUBLIC`, `LIMITED`, `PRIVATE`. - `Metadata file not found: competition-metadata.json` — run `init` first, or pass `-p` pointing at the folder that contains the file. ### Competition metadata reference All fields go in `competition-metadata.json` (camelCase keys). **Required:** | Field | Type | Notes | |---|---|---| | `title` | string | Display title shown on the competition page. | | `slug` | string | URL slug; lowercase, hyphens, must be unique site-wide and must not be all digits or all hyphens. | | `briefDescription` | string | One-line subtitle under the title. | | `privacy` | string | One of `PUBLIC`, `LIMITED`, `PRIVATE`. | **Optional:** | Field | Type | Notes | |---|---|---| | `disableKernels` | bool | If `true`, notebook submissions are disabled. | | `hackathon` | bool | Create as a hackathon competition. | | `restrictLinkToEmailList` | bool | Restrict invite-link joiners to a host-maintained allowlist. | | `cloneCompetitionId` | int | If set, clone configuration / pages / data / evaluation setup from this competition. | | `cloneExcludeCompetitionData` | bool | If cloning, skip copying the data (solution, sandbox submissions, images, databundles). | | `clonePageNames` | string[] | If cloning, copy only these page names. Omit/null to copy all. | | `licenseId` | int | License ID for the competition data. | | `organizationId` | int | Tie this competition to an organization (read-only access for all org members). | | `numPrizes` | int | Number of leaderboard prize positions. | | `reward` | object | See below. | **`reward` object:** ```json { "id": "USD", "quantity": 25000, "clarification": "Total prize pool split across the top 5 teams." } ``` `reward.id` is one of: `USD`, `KUDOS`, `AUD`, `EUR`, `JOBS`, `SWAG`, `GBP`, `KNOWLEDGE`, `PRIZES`. `clarification` is optional free-form text shown next to the prize. --- ## `kaggle competitions pages create` Creates a new page (description, rules, evaluation, data-description, etc.) on a competition you host. **Usage:** ```bash kaggle competitions pages create --page-name -f \ [--mime-type ] [--post-title ""] [--publish] ``` **Arguments:** - `<competition>`: The competition slug. **Options:** - `--page-name <page-name>` (required): Page name (e.g. `description`, `rules`, `evaluation`, `data-description`, `prizes`). Conventional names are recognized by the competition page UI; new names are allowed but won't be shown in the standard tabs. - `-f, --file <path>` (required): Path to a file whose contents become the page body. - `--mime-type <type>` (optional): MIME type of the content. Defaults to `text/html` server-side. - `--post-title "<title>"` (optional): Title shown above the page body. Defaults to the page name. - `--publish` (optional): Publish the page immediately. Without this flag the page is created in a staged (unpublished) state so you can review it before going live. **Example:** ```bash # Create the rules page in a staged (not-yet-published) state. kaggle competitions pages create my-comp --page-name rules -f ./rules.md \ --mime-type text/markdown --post-title "Competition Rules" # When you're ready to make it visible to participants: kaggle competitions pages update my-comp --page-name rules --publish ``` Each page exists as a single record; `--publish` / `--unpublish` toggles its visibility rather than creating separate draft and live copies. To swap in new content later, use [`kaggle competitions pages update`](#kaggle-competitions-pages-update) — a second `create` for the same page name will be rejected. You can list and inspect existing pages with `kaggle competitions pages` (or the explicit `kaggle competitions pages list`), modify one in place with [`kaggle competitions pages update`](#kaggle-competitions-pages-update), or remove one with [`kaggle competitions pages delete`](#kaggle-competitions-pages-delete). --- ## `kaggle competitions pages update` Updates fields on an existing competition page. Only the flags you supply are sent (the FieldMask is built from which arguments are non-default), so this is also how you publish or unpublish a page in place. **Usage:** ```bash kaggle competitions pages update <competition> --page-name <current-name> \ [-f <path>] [--new-name <name>] [--mime-type <type>] \ [--post-title "<title>"] [--publish | --unpublish] ``` **Arguments:** - `<competition>`: The competition slug. **Options:** - `--page-name <current-name>` (required): The page's current name (used as the identifier; rename via `--new-name`). - `-f, --file <path>` (optional): Path to a file with the new page body. - `--new-name <name>` (optional): Rename the page. - `--mime-type <type>` (optional): New MIME type of the content. - `--post-title "<title>"` (optional): New title shown above the page content. - `--publish` / `--unpublish` (optional, mutually exclusive): Publish or unpublish the page. At least one update flag is required. **Examples:** ```bash # Publish a staged page without changing its content. kaggle competitions pages update my-comp --page-name rules --publish # Swap in new content and update the visible title in one call. kaggle competitions pages update my-comp --page-name rules \ -f ./rules-v2.md --post-title "Competition Rules (v2)" # Rename a page. kaggle competitions pages update my-comp --page-name evaluation \ --new-name scoring ``` **Note:** a small set of pages is reserved by the backend and cannot be renamed; attempting to rename one returns an error from the server. --- ## `kaggle competitions pages delete` Deletes a page from a competition you host. Prompts for confirmation unless `-y/--yes` is passed (matches the existing `kaggle datasets delete` / `kaggle kernels delete` patterns). **Usage:** ```bash kaggle competitions pages delete <competition> --page-name <name> [-y] ``` **Arguments:** - `<competition>`: The competition slug. **Options:** - `--page-name <name>` (required): Name of the page to delete. - `-y, --yes` (optional): Skip the confirmation prompt — useful for scripts. **Examples:** ```bash # Interactive: prompts "Are you sure you want to delete the page 'faq' ...?" kaggle competitions pages delete my-comp --page-name faq # Scripted: skip the prompt. kaggle competitions pages delete my-comp --page-name faq -y ``` **Note:** a small set of pages is protected by the backend and cannot be deleted; attempting to delete one returns an error from the server. Deletion is not recoverable — there is no "undelete". List pages first with `kaggle competitions pages list <competition>` if you're unsure of the name. --- ## `kaggle competitions hosts` Lists the hosts (users with host access) for a competition. Useful for confirming who can edit settings, upload data, or launch — especially after adding or removing collaborators via the web UI. **Usage:** ```bash kaggle competitions hosts <competition> [-v | --format json] ``` **Arguments:** - `<competition>`: The competition slug. **Examples:** ```bash # Table output. kaggle competitions hosts my-comp # CSV — useful for piping into other tools. kaggle competitions hosts my-comp -v # JSON. kaggle competitions hosts my-comp --format json ``` Output columns: `userName`, `displayName`, `id`, `profileUrl`. --- ## `kaggle competitions host-add` Grants host access on a competition you host to another Kaggle user. Hosts can edit settings, upload data, and launch the competition, so you are asked to confirm before the change is made. **Usage:** ```bash kaggle competitions host-add <competition> -u <user> [-y] ``` **Arguments:** - `<competition>`: The competition slug. **Options:** - `-u, --user <USER>`: Kaggle user name (URL slug, e.g. `kerneler`) of the user to add as a host. Required. - `-y, --yes`: Skip the confirmation prompt. - `-q, --quiet`: Suppress the "Using competition" message. **Examples:** ```bash # Prompts for confirmation before granting access. kaggle competitions host-add my-comp -u alice # Skip the prompt (for scripts). kaggle competitions host-add my-comp -u alice -y ``` Verify the result with `kaggle competitions hosts my-comp`. > **Note:** This command is named `host-add` rather than `hosts add` because > `hosts` takes the competition as a positional argument, and argparse cannot > distinguish a competition slug from a subcommand name. --- ## `kaggle competitions settings get` Shows the unified settings blob for a competition you host — the same set of fields the "Settings" tab exposes in the web UI, covering general info, access & teams, key dates, submissions & leaderboard behavior, code competition parameters, and host attribution. By default the output is grouped by UI section and hides fields left at their type default (unset strings, `false` booleans, zero ints). Pass `--json` for the raw blob (camelCase keys, matching the update payload format). **Usage:** ```bash kaggle competitions settings get <competition> [--json] ``` **Arguments:** - `<competition>`: The competition slug. **Examples:** ```bash # Grouped, human-readable summary. kaggle competitions settings get my-comp # Machine-readable dump — pipe into jq, or save + edit + feed back to update. kaggle competitions settings get my-comp --json > settings.json ``` --- ## `kaggle competitions settings update` Applies a partial update to a competition's settings. You author a JSON or YAML file containing only the fields you want to change; the CLI builds the server-side FieldMask from the keys present in the file, so unspecified fields are left alone. The typical loop is: 1. `kaggle competitions settings get my-comp --json > settings.json` — pull the current values. 2. Edit the file down to just the fields you want to change (delete the rest). 3. `kaggle competitions settings update my-comp -f ./settings.json`. **Usage:** ```bash kaggle competitions settings update <competition> -f <path> [--json] ``` **Arguments:** - `<competition>`: The competition slug. **Options:** - `-f, --from-file <path>` (required): JSON or YAML file with the fields to update. Extension picks the parser (`.yaml`/`.yml` → YAML, anything else → JSON). Keys may be `snake_case` (matches the SDK) or `camelCase` (matches the `--json` output of `settings get`). - `--json` (optional): After the update, print the returned settings as JSON instead of the grouped text view. **Examples:** Toggle a single boolean: ```json // disable-leaderboard.json { "has_leaderboard": false } ``` ```bash kaggle competitions settings update my-comp -f ./disable-leaderboard.json ``` Set the competition deadline: ```json // deadline.json { "deadline": "2027-02-01T23:59:00Z" } ``` ```bash kaggle competitions settings update my-comp -f ./deadline.json ``` Bump the code-competition runtime caps and set the competition and team-merger deadlines (YAML, mixing types): ```yaml # tune.yaml max_cpu_runtime_minutes: 540 max_gpu_runtime_minutes: 720 deadline: 2027-02-01T23:59:00Z team_merger_explicit_deadline: 2027-01-15T00:00:00Z rules_required: true ``` ```bash kaggle competitions settings update my-comp -f ./tune.yaml ``` **Type notes:** - Booleans → JSON `true`/`false` (or YAML equivalents). - Numeric fields → plain numbers (`240`, `1.5`). - Datetime fields → ISO-8601 strings (`"2027-01-01T00:00:00Z"` or with an explicit offset). - Enum fields (`host_segment`, `publicly_cloneable`) → the enum member name as a string; either the full name (`"HOST_SEGMENT_FEATURED"`) or the short suffix (`"FEATURED"`) works. **Common errors:** - `Unknown competition setting: '<name>'` — the field name isn't in `CompetitionSettings`. Check `settings get --json` for the exact keys. - `Field '<name>' expects a bool, got str` — the file has a string where a boolean is required (e.g. `"true"` instead of `true`). - `not a valid HostSegment. Allowed: ...` — the enum value you passed isn't a member; the error lists the accepted names. - Some settings are gated to Kaggle admins (marked "ADMIN ONLY" in the proto — e.g. `host_segment`, `directly_responsible_user_id`) and the server will reject writes to them for non-admin hosts. --- ## `kaggle competitions launch` Launches a competition you host. Without `--at`, the competition is launched immediately. With `--at`, the backend schedules the launch for the given UTC instant. **Usage:** ```bash kaggle competitions launch <competition> [--at <ISO-8601 UTC>] ``` **Arguments:** - `<competition>`: The competition slug. **Options:** - `--at <iso>`: Schedule launch for a future UTC time. Accepts ISO-8601 (e.g. `2027-01-01T00:00:00Z` or `2027-01-01T00:00:00+00:00`). The competition is launched immediately if omitted. **Examples:** ```bash # Launch right now. kaggle competitions launch my-comp # Schedule the launch for midnight UTC on 2027-01-01. kaggle competitions launch my-comp --at 2027-01-01T00:00:00Z ``` A competition can only be launched once. Subsequent calls will be rejected by the backend. --- ## `kaggle competitions data update` Creates a new version of the data files for a competition you host. Uploads via the standard blob-upload pipeline, then sends a single request bundling the uploaded tokens. Each update **replaces the prior version's file set in full** — there is no per-file "keep from previous" mode in v1, so list every file you want in the new version. **Usage:** ```bash kaggle competitions data update <competition> -p <path> -m "<version notes>" \ [--rerun] [--include-hidden] [--ignore-patterns <patterns>] ``` **Arguments:** - `<competition>`: The competition slug. **Options:** - `-p, --path <path>` (required): Either a **directory** (walked recursively — every file becomes an upload with its relative path preserved in the API's `name` field, e.g. `train/images/img1.jpg`), or a **single archive file** (e.g. a pre-packed `.zip` or `.tar`) uploaded as-is. Sub-directories are always traversed; hidden entries (see `--include-hidden`) are the only files skipped by default. - `-m, --message "<notes>"` (required): Notes describing this version (e.g. `"Added test set"`). - `--rerun` (optional): Update the RERUN databundle — the private host-only data swapped in during rerun scoring. Requires Kaggle admin access for now. Without this flag, the update targets the PUBLIC databundle (what participants download). - `--include-hidden` (optional): Upload hidden files and traverse hidden sub-directories (names starting with `.` — e.g. `.DS_Store`, `.git/`, `.gitignore`). Skipped by default so you don't accidentally publish OS metadata or version-control detritus. - `--ignore-patterns <patterns>` (optional): Patterns to ignore when uploading files/dirs. Can be specified multiple times. Note that default ignore patterns (like `.git/`, `.cache/`, `.huggingface/`) are bypassed when `--include-hidden` is True. **Examples:** ```bash # Update using a directory tree (recurses into sub-folders). kaggle competitions data update my-comp -p ./data -m "Initial release" # Update using a pre-packed archive as a single file (useful when you already # need a zip for other purposes, or for directory-shaped file formats like # Zarr). kaggle competitions data update my-comp -p ./data.zip -m "Initial release" # New version with a bug-fix. kaggle competitions data update my-comp -p ./data -m "Fix label encoding in train.csv" # Update the private rerun-scoring data. kaggle competitions data update my-comp -p ./rerun-data \ -m "Held-out test set" --rerun ``` **A note on directory-shaped file formats:** some formats (Zarr, some TensorFlow SavedModel layouts, etc.) are on-disk directories that are logically a single unit. If you pass a directory containing such a format, the recursive walk uploads each internal chunk as its own file — often what you want for Zarr, since participants can then stream individual chunks. If you'd rather keep the format as an opaque single upload, pre-pack it into a `.zip` or `.tar` and pass that file to `-p` instead. The command prints the public URL plus the new `databundle_id` and `databundle_version_id` on success. --- ## `kaggle competitions solution create` Uploads the private solution CSV for a competition you host. The solution is what the backend scores submissions against — one row per row in the sample submission, with the same column shape. After uploading, the backend runs preprocessing / sampling; poll [`kaggle competitions solution status`](#kaggle-competitions-solution-status) until it's `ready` before opening submissions. The file is uploaded via the standard blob-upload pipeline, then the resulting token is passed to `CreateCompetitionSolution`. **Usage:** ```bash kaggle competitions solution create <competition> -p <path> [-q] ``` **Arguments:** - `<competition>`: The competition slug. **Options:** - `-p, --path <path>` (required): Path to a single CSV file. Must be a single file — directories are rejected. The CSV shape must match a submission file (same columns as `sample_submission.csv`). - `-q, --quiet` (optional): Suppress per-file upload progress lines. **Example:** ```bash kaggle competitions solution create my-comp -p ./solution.csv # → Solution uploaded for "my-comp". Run 'kaggle competitions solution status my-comp' to check readiness. ``` Re-uploading a solution replaces the prior one. Note that this only works pre-launch; after launch the solution file is frozen. --- ## `kaggle competitions solution status` Shows the setup status for a competition's solution file — whether preprocessing/sampling has finished, any errors reported by the backend, and (for legacy C# metrics) the auto-inferred column mapping and required metric columns. Poll this after `solution create` (and after `data update` — some setup steps run against the databundle) until `Ready: true`. If `Setup error:` is set, stop polling and fix the underlying issue. **Usage:** ```bash kaggle competitions solution status <competition> [--json] ``` **Arguments:** - `<competition>`: The competition slug. **Options:** - `--json` (optional): Emit the raw status as JSON instead of the human-readable view. **Examples:** ```bash # Human-readable summary. kaggle competitions solution status my-comp # → Ready: true # Solution file: solution.csv — 12.3KB — uploaded 2027-01-01T00:00:00+00:00 # total=1000, public=300, private=700 # Machine-readable — useful in a polling loop. kaggle competitions solution status my-comp --json ``` **Fields you might see (human view):** - `Ready: true|false` — whether scoring is unblocked. - `Setup error: <msg>` — populated if preprocessing failed. Surfaced prominently; stop polling when it appears. - `Kernels metric: true` — the competition's scoring metric is a Kernels metric. Kernels metrics auto-detect their column mapping; the host only needs to wait for `Ready` to flip true. - `Row ID column: <name>` — for Kernels metrics, the auto-detected row-id column. - `Solution file: <name> — <size> — uploaded <timestamp>` and `total=..., public=..., private=...` — solution file metadata once the upload is processed. - `Column mapping:` — for legacy C# metrics, the current mapping from metric column name to CSV column name. - `Required columns:` — for legacy C# metrics, the metric column slots the host needs to fill (name + expected data type). --- ### Competitions # Competitions Commands Commands for interacting with Kaggle competitions. For tutorials on how to submit to competitions : * [How to Submit to a Competition](./tutorials.md#tutorial-how-to-submit-to-a-competition) * [How to Submit to a Code Competition](./tutorials.md#tutorial-how-to-submit-to-a-code-competition) ## `kaggle competitions list` Lists available competitions. **Usage:** ```bash kaggle competitions list [options] ``` **Options:** * `--group <GROUP>`: Filter by competition group. Valid options: `general`, `entered`, `inClass`. * `--category <CATEGORY>`: Filter by competition category. Valid options: `all`, `featured`, `research`, `recruitment`, `gettingStarted`, `masters`, `playground`. * `--sort-by <SORT_BY>`: Sort results. Valid options: `grouped`, `prize`, `earliestDeadline`, `latestDeadline`, `numberOfTeams`, `recentlyCreated` (default: `latestDeadline`). * `-p, --page <PAGE>`: Page number for results (default: 1). * `-s, --search <SEARCH_TERM>`: Search term. * `-v, --csv`: Print results in CSV format. * `--format`: Output format (`csv`, `table`, `json`, or a field projection). See [output_format.md](./output_format.md). **Output columns:** `ref`, `deadline`, `category`, `reward`, `teamCount`, `userHasEntered`, `userRank` `userRank` is your public leaderboard position when you have entered the competition. It is `0` when you have not entered, or when no public rank is available yet. **Example:** List featured competitions in the general group, sorted by prize: ```bash kaggle competitions list --group general --category featured --sort-by prize ``` List entered competitions with rank in CSV format: ```bash kaggle competitions list --group entered -v ``` **Purpose:** This command helps you discover new competitions or find specific ones based on various criteria. Use `--group entered` to see your rank across competitions you have joined. ## `kaggle competitions files` Lists files for a specific competition. **Usage:** ```bash kaggle competitions files <COMPETITION> [options] ``` **Arguments:** * `<COMPETITION>`: Competition URL suffix (e.g., `titanic`). **Options:** * `-v, --csv`: Print results in CSV format. * `-q, --quiet`: Suppress verbose output. * `--page-token <PAGE_TOKEN>`: Page token for results paging. * `--page-size <PAGE_SIZE>`: Number of items to show on a page (default: 20, max: 200). **Example:** List the first 3 files for the "titanic" competition in CSV format, quietly: ```bash kaggle competitions files titanic --page-size=3 -v -q ``` **Purpose:** Use this command to see the data files available for a competition before downloading them. ## `kaggle competitions download` Downloads competition files. **Usage:** ```bash kaggle competitions download <COMPETITION> [options] ``` **Arguments:** * `<COMPETITION>`: Competition URL suffix (e.g., `titanic`). **Options:** * `-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). * `-w, --wp`: Download files to the current working path (equivalent to `-p .`). * `-o, --force`: Force download, overwriting existing files. * `-q, --quiet`: Suppress verbose output. **Examples:** 1. Download all files for the "titanic" competition to the current directory, overwriting existing files, quietly: ```bash kaggle competitions download titanic -w -o -q ``` 2. Download the `test.csv` file from the "titanic" competition to a folder named `tost`: ```bash kaggle competitions download titanic -f test.csv -p tost ``` **Purpose:** This command allows you to get the necessary data files for a competition onto your local machine. ## `kaggle competitions submit` Makes a new submission to a competition. **Usage:** ```bash kaggle competitions submit <COMPETITION> -f <FILE_NAME> -m <MESSAGE> [options] ``` **Arguments:** * `<COMPETITION>`: Competition URL suffix (e.g., `house-prices-advanced-regression-techniques`). * `-f, --file <FILE_NAME>`: The submission file. * `-m, --message <MESSAGE>`: The submission message. **Options:** * `-k, --kernel <KERNEL>`: Name of the kernel (notebook) to submit (for code competitions). * `-v, --version <VERSION>`: Version of the kernel to submit (e.g. `2`). * `-q, --quiet`: Suppress verbose output. * `--sandbox`: Mark submission as a sandbox submission (competition hosts/admins only). * `--wait [SECONDS]`: Wait for the submission to finish scoring, printing the public score when done. Optionally pass a timeout in seconds (`0` or no value = wait up to 12 hours, the maximum notebook runtime). Exits non-zero if scoring fails or the timeout is reached. * `--poll-interval <SECONDS>`: Maximum seconds between status polls while waiting (default: `60`, minimum: `5`). Polling starts at 5s and increases automatically. On a successful submission the command prints the numeric submission ref, e.g. `Submission ref: 12345678`. You can look that submission up later with [`kaggle competitions submission`](#kaggle-competitions-submission). **Example: Standard (not code) competition:** Submit `sample_submission.csv` to the "house-prices-advanced-regression-techniques" competition with the message "Test message": ```bash kaggle competitions submit house-prices-advanced-regression-techniques -f sample_submission.csv -m "Test message" ``` **Example: Code competition:** Submit the `submission.csv` produced by version `3` of your `<YOUR_USERNAME>/rsna-submission` for the `rsna-2024-lumbar-spine-degenerative-classification` competition: ```bash kaggle competitions submit rsna-2024-lumbar-spine-degenerative-classification -f submission.csv -k <YOUR_USERNAME>/rsna-submission -v 3 -m "Test message" ``` **Example: Submit and wait for the score (useful in CI):** Submit and block until scoring finishes (up to a 10-minute timeout), then print the public score: ```bash kaggle competitions submit house-prices-advanced-regression-techniques -f sample_submission.csv -m "CI run" --wait 600 ``` The command exits `0` once the submission is scored and non-zero if scoring fails or the timeout is reached, so it can gate a pipeline. **Purpose:** Use this command to upload your predictions or code to a competition for scoring. ## `kaggle competitions submission` Shows the status and score of a single submission by its numeric ref (as printed by `kaggle competitions submit`). **Usage:** ```bash kaggle competitions submission <SUBMISSION_REF> ``` **Arguments:** * `<SUBMISSION_REF>`: The numeric submission ref printed by `kaggle competitions submit`. **Example:** ```bash kaggle competitions submission 12345678 ``` Output: ``` Submission Ref: 12345678 Status: COMPLETE Public Score: 0.98765 Private Score: Description: Test message Submission Date: 2026-07-19 12:00:00 ``` **Purpose:** Use this command to check whether a submission has finished scoring and to read its public score — for example, after submitting without `--wait`, or from a script polling for results. ## `kaggle competitions submissions` Shows your past submissions for a competition. **Usage:** ```bash kaggle competitions submissions <COMPETITION> [options] ``` **Arguments:** * `<COMPETITION>`: Competition URL suffix (e.g., `house-prices-advanced-regression-techniques`). **Options:** * `-v, --csv`: Print results in CSV format. * `-q, --quiet`: Suppress verbose output. **Example:** Show submissions for "house-prices-advanced-regression-techniques" in CSV format, quietly: ```bash kaggle competitions submissions house-prices-advanced-regression-techniques -v -q ``` **Purpose:** This command allows you to review your previous submission attempts and their scores. ## `kaggle competitions submission-download` Downloads the submitted file for a single submission by its numeric id. **Usage:** ```bash kaggle competitions submission-download <SUBMISSION_ID> [options] ``` **Arguments:** * `<SUBMISSION_ID>`: The numeric submission id printed by `kaggle competitions submit`, or listed by `kaggle competitions submissions <COMPETITION>`. **Options:** * `-p, --path <PATH>`: Folder to download the file to. Defaults to the current working directory's Kaggle download location. * `-o, --force`: Download even if a local copy already exists (skips the up-to-date check). * `-q, --quiet`: Suppress verbose output. **Example:** Download the file for submission `12345678` into `./subs`: ```bash kaggle competitions submission-download 12345678 -p ./subs ``` **Purpose:** Use this command to retrieve the exact file you (or a teammate) submitted — for example, to inspect an old submission or reproduce a scored result. ## `kaggle competitions leaderboard` Gets competition leaderboard information. **Usage:** ```bash kaggle competitions leaderboard <COMPETITION> [options] ``` **Arguments:** * `<COMPETITION>`: Competition URL suffix (e.g., `titanic`). **Options:** * `-s, --show`: Show the top of the leaderboard in the console. * `-d, --download`: Download the entire leaderboard to a CSV file. * `-p, --path <PATH>`: Folder to download the leaderboard to (if `-d` is used). * `-v, --csv`: Print results in CSV format (used with `-s`). * `-q, --quiet`: Suppress verbose output. **Examples:** 1. Download the "titanic" leaderboard to a folder named `leaders`, quietly: ```bash kaggle competitions leaderboard titanic -d -p leaders -q ``` 2. Download the leaderboard and save it to `leaderboard.txt`: ```bash kaggle competitions leaderboard titanic > leaderboard.txt ``` **Purpose:** This command lets you view your ranking and the scores of other participants in a competition. ## `kaggle competitions topics list` Lists discussion topics for a competition. **Usage:** ```bash 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`). Optional if default competition is configured. **Options:** * `-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. **Example:** List discussion topics for the "titanic" competition sorted by most recent: ```bash kaggle competitions topics list titanic -s recent ``` **Purpose:** This command lets you browse discussion topics for a specific competition. ## `kaggle competitions topics show` Displays a competition discussion topic with all comments in tree form. **Usage:** ```bash 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, 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:** Show topic 12345 from the "titanic" competition: ```bash 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. ## `kaggle competitions topic-messages` Lists messages within a competition discussion topic. > **Deprecated:** This command is deprecated in favor of `kaggle competitions topics show`. It will be removed in a future release. **Usage:** ```bash kaggle competitions topic-messages <COMPETITION> <TOPIC_ID> [options] ``` **Arguments:** * `<COMPETITION>`: Competition URL suffix (e.g., `titanic`). * `<TOPIC_ID>`: The discussion topic id. **Options:** * `-s, --sort-by <SORT_BY>`: Sort order. Valid options: `best`, `new`, `old`. * `-n, --page-size <PAGE_SIZE>`: Max top-level messages to return; `-1` for all. * `-v, --csv`: Print results in CSV format. * `-q, --quiet`: Suppress verbose output. **Example:** List all messages for topic 12345 in the "titanic" competition, sorted by newest first: ```bash kaggle competitions topic-messages titanic 12345 -s new -n -1 ``` **Purpose:** This command displays the messages within a specific competition discussion topic. --- ### Configuration # Kaggle CLI Configuration The Kaggle CLI uses a configuration file to store settings such as your API credentials and default values for commands. ## Configuration Commands ### `config view` Displays the current configuration values. **Usage:** ```bash kaggle config view ``` **Purpose:** This command allows you to inspect the current settings of your Kaggle CLI, such as the configured API endpoint, proxy settings, and default competition. ### `config set` Sets a specific configuration value. **Usage:** ```bash kaggle config set -n <NAME> -v <VALUE> ``` **Arguments:** * `-n, --name <NAME>`: The name of the configuration parameter to set. Valid options are `competition`, `path`, and `proxy`. * `-v, --value <VALUE>`: The value to set for the configuration parameter. * For `competition`: The competition URL suffix (e.g., `titanic`). * For `path`: The default folder where files will be downloaded. * For `proxy`: The proxy server URL. **Example:** Set the default competition to "titanic": ```bash kaggle config set -n competition -v titanic ``` **Purpose:** Use this command to customize the behavior of the Kaggle CLI, such as setting a default competition to avoid specifying it in every command, defining a default download path, or configuring a proxy server. ### `config unset` Clears a specific configuration value, reverting it to its default. **Usage:** ```bash kaggle config unset -n <NAME> ``` **Arguments:** * `-n, --name <NAME>`: The name of the configuration parameter to clear. Valid options are `competition`, `path`, and `proxy`. **Example:** Clear the default competition: ```bash kaggle config unset -n competition ``` **Purpose:** This command removes a previously set configuration value, allowing the CLI to use its default behavior or prompt for the value if required. ## 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. This file contains your API username and key: ```json {"username":"YOUR_USERNAME","key":"YOUR_API_KEY"} ``` You can download this file from your Kaggle account page (`https://www.kaggle.com/<YOUR_USERNAME>/account`) and place it in the correct directory. Alternatively, you can set the `KAGGLE_USERNAME` and `KAGGLE_KEY` environment variables. --- ### Datasets # Datasets Commands Commands for interacting with Kaggle datasets. ## `kaggle datasets list` Lists available datasets. **Usage:** ```bash kaggle datasets list [options] ``` **Options:** * `--sort-by <SORT_BY>`: Sort results. Valid options: `hottest`, `votes`, `updated`, `active` (default: `hottest`). * `--size <SIZE_CATEGORY>`: DEPRECATED. Use `--min-size` and `--max-size`. * `--file-type <FILE_TYPE>`: Filter by file type. Valid options: `all`, `csv`, `sqlite`, `json`, `bigQuery`. * `--license <LICENSE_NAME>`: Filter by license. Valid options: `all`, `cc`, `gpl`, `odb`, `other`. * `--tags <TAG_IDS>`: Filter by tags (comma-separated tag IDs). * `-s, --search <SEARCH_TERM>`: Search term. * `-m, --mine`: Display only your datasets. * `--user <USER>`: Filter by a specific user or organization. * `-p, --page <PAGE>`: Page number for results (default: 1). * `-v, --csv`: Print results in CSV format. * `--max-size <BYTES>`: Maximum dataset size in bytes. * `--min-size <BYTES>`: Minimum dataset size in bytes. **Examples:** 1. List your own datasets: ```bash kaggle datasets list -m ``` 2. List CSV datasets, page 2, sorted by last updated, containing "student" in their title, with size between 13000 and 15000 bytes: ```bash kaggle datasets list --file-type csv --page 2 --sort-by updated -s student --min-size 13000 --max-size 15000 ``` 3. List datasets with an ODB license, tagged with "internet", and matching the search term "telco": ```bash kaggle datasets list --license odb --tags internet --search telco ``` **Purpose:** This command helps you find datasets on Kaggle based on various criteria like owner, file type, tags, and size. ## `kaggle datasets files` Lists files for a specific dataset. **Usage:** ```bash kaggle datasets files <DATASET> [options] ``` **Arguments:** * `<DATASET>`: Dataset URL suffix in the format `owner/dataset-name` (e.g., `kerneler/brazilian-bird-observation-metadata-from-wikiaves`). **Options:** * `-v, --csv`: Print results in CSV format. * `--page-token <PAGE_TOKEN>`: Page token for results paging. * `--page-size <PAGE_SIZE>`: Number of items to show on a page (default: 20, max: 200). **Example:** List the first 7 files for the dataset `kerneler/brazilian-bird-observation-metadata-from-wikiaves`: ```bash kaggle datasets files kerneler/brazilian-bird-observation-metadata-from-wikiaves --page-size=7 ``` **Purpose:** Use this command to see the individual files within a dataset before downloading. ## `kaggle datasets download` Downloads dataset files. **Usage:** ```bash kaggle datasets download <DATASET> [options] ``` **Arguments:** * `<DATASET>`: Dataset URL suffix (e.g., `willianoliveiragibin/pixar-films`). **Options:** * `-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). * `-w, --wp`: Download files to the current working path. * `--unzip`: Unzip the downloaded file (deletes the .zip file afterwards). * `-o, --force`: Force download, overwriting existing files. * `-q, --quiet`: Suppress verbose output. **Examples:** 1. Download all files for the dataset `willianoliveiragibin/pixar-films`: ```bash kaggle datasets download -d willianoliveiragibin/pixar-films ``` 2. Download the dataset `goefft/public-datasets-with-file-types-and-columns`, unzip it into the `tmp` folder, overwriting if necessary, and suppress output: ```bash kaggle datasets download goefft/public-datasets-with-file-types-and-columns -p tmp --unzip -o -q ``` 3. Download the specific file `dataset_results.csv` from `goefft/public-datasets-with-file-types-and-columns` to the current working directory, quietly, and force overwrite: ```bash kaggle datasets download goefft/public-datasets-with-file-types-and-columns -f dataset_results.csv -w -q -o ``` **Purpose:** This command allows you to retrieve dataset files for local use. ## `kaggle datasets init` Initializes a metadata file (`dataset-metadata.json`) for creating a new dataset. See [metadata file format](./datasets_metadata.md). **Usage:** ```bash kaggle datasets init -p <FOLDER_PATH> ``` **Options:** * `-p, --path <FOLDER_PATH>`: The path to the folder where the `dataset-metadata.json` file will be created (defaults to the current directory). **Example:** Initialize a dataset metadata file in the `tests/dataset` folder: ```bash kaggle datasets init -p tests/dataset ``` **Purpose:** This command creates a template `dataset-metadata.json` file that you need to edit before creating a new dataset on Kaggle. This file contains information like the dataset title, ID (slug), and licenses. ## `kaggle datasets create` Creates a new dataset on Kaggle. **Usage:** ```bash kaggle datasets create -p <FOLDER_PATH> [options] ``` **Options:** * `-p, --path <FOLDER_PATH>`: Path to the folder containing the data files and the `dataset-metadata.json` file (defaults to the current directory). * `-u, --public`: Make the dataset public (default is private). * `-q, --quiet`: Suppress verbose output. * `-t, --keep-tabular`: Do not convert tabular files to CSV (default is to convert). * `-r, --dir-mode <MODE>`: How to handle directories: `skip` (ignore), `zip` (compressed upload), `tar` (uncompressed upload) (default: `skip`). * `--ignore-patterns <PATTERNS>`: Patterns of files/dirs to ignore. Can be specified multiple times. **Example:** Create a new public dataset from the files in `tests/dataset`, quietly, without converting tabular files, and skipping subdirectories. (Assumes `dataset-metadata.json` in `tests/dataset` has been properly edited with title and slug): ```bash # Example: Edit dataset-metadata.json first # sed -i 's/INSERT_TITLE_HERE/My Dataset Title/' tests/dataset/dataset-metadata.json # sed -i 's/INSERT_SLUG_HERE/my-dataset-slug/' tests/dataset/dataset-metadata.json kaggle datasets create -p tests/dataset --public -q -t -r skip ``` **Purpose:** This command uploads your local data files and the associated metadata to create a new dataset on Kaggle. ## `kaggle datasets version` Creates a new version of an existing dataset. **Usage:** ```bash kaggle datasets version -p <FOLDER_PATH> -m <VERSION_NOTES> [options] ``` **Options:** * `-p, --path <FOLDER_PATH>`: Path to the folder containing the updated data files and `dataset-metadata.json` (defaults to current directory). * `-m, --message <VERSION_NOTES>`: (Required) Message describing the new version. * `-q, --quiet`: Suppress verbose output. * `-t, --keep-tabular`: Do not convert tabular files to CSV. * `-r, --dir-mode <MODE>`: Directory handling mode (`skip`, `zip`, `tar`). * `-d, --delete-old-versions`: Delete old versions of this dataset. * `--ignore-patterns <PATTERNS>`: Patterns of files/dirs to ignore. Can be specified multiple times. **Example:** Create a new version of a dataset using files from `tests/dataset` with version notes "Updated data", quietly, keeping tabular formats, skipping directories, and deleting old versions: ```bash kaggle datasets version -m "Updated data" -p tests/dataset -q -t -r skip -d ``` **Purpose:** Use this command to update an existing dataset with new files or metadata changes. ## `kaggle datasets metadata` Downloads metadata for a dataset or updates existing from local metadata. **Usage:** ```bash kaggle datasets metadata <DATASET> [options] ``` **Arguments:** * `<DATASET>`: Dataset URL suffix (e.g., `goefft/public-datasets-with-file-types-and-columns`). **Options:** * `-p, --path <PATH>`: Directory to download/update metadata file (`dataset-metadata.json`). Defaults to current working directory. * `--update`: Update the existing dataset version's metadata using the contents of the local metadata JSON file. (e.g. "push" from local) **Example:** Download metadata for the dataset `goefft/public-datasets-with-file-types-and-columns` into the `tests/dataset` folder: ```bash kaggle datasets metadata goefft/public-datasets-with-file-types-and-columns -p tests/dataset ``` **Purpose:** This command allows you to fetch the `dataset-metadata.json` file for an existing dataset, which can be useful for inspection or as a template for creating a new version. ## `kaggle datasets status` Gets the creation status of a dataset. **Usage:** ```bash kaggle datasets status <DATASET> ``` **Arguments:** * `<DATASET>`: Dataset URL suffix (e.g., `goefft/public-datasets-with-file-types-and-columns`). **Example:** Get the status of the dataset `goefft/public-datasets-with-file-types-and-columns`: ```bash kaggle datasets status goefft/public-datasets-with-file-types-and-columns ``` **Purpose:** After creating or updating a dataset, this command helps you check if the process was successful or if there were any issues. ## `kaggle datasets delete` Deletes a dataset from Kaggle. **Usage:** ```bash kaggle datasets delete <DATASET> [options] ``` **Arguments:** * `<DATASET>`: Dataset URL suffix (e.g., `username/dataset-slug`). **Options:** * `-y, --yes`: Automatically confirm deletion without prompting. **Example:** Delete the dataset `username/dataset-slug` and automatically confirm: ```bash kaggle datasets delete username/dataset-slug --yes ``` **Purpose:** This command permanently removes one of your datasets from Kaggle. Use with caution. ## `kaggle datasets topics list` Lists discussion topics for a dataset. **Usage:** ```bash kaggle datasets topics list <DATASET> [options] ``` **Arguments:** * `<DATASET>`: Dataset ref in format `<owner>/<dataset-slug>` (e.g., `zillow/zecon`). **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 zillow/zecon dataset: ```bash kaggle datasets topics list zillow/zecon --sort-by recent ``` **Purpose:** This command lets you browse discussion topics for a specific dataset. ## `kaggle datasets topics show` Displays a dataset discussion topic with all comments in tree form. **Usage:** ```bash kaggle datasets topics show <TOPIC_REF> [options] ``` **Arguments:** * `<TOPIC_REF>`: A topic reference, which can be: * `<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:** * `--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 datasets topics show zillow/zecon/12345 ``` **Purpose:** This command displays a full discussion topic along with all of its comments rendered in an indented tree structure. --- ### Datasets Metadata The Kaggle API follows the [Data Package specification](https://frictionlessdata.io/specs/data-package/) for specifying metadata when creating new Datasets and Dataset versions. Next to your files, you have to put a special `dataset-metadata.json` file in your upload folder alongside the files for each new Dataset (version). Here's a basic example for `dataset-metadata.json`: ``` { "title": "My Awesome Dataset", "id": "timoboz/my-awesome-dataset", "licenses": [{"name": "CC0-1.0"}] } ``` You can also use the API command `kaggle datasets init -p /path/to/dataset` to have the API create this file for you. Here's an example containing file metadata: ``` { "title": "My Awesome Dataset", "subtitle": "My awesomer subtitle", "description": "My awesomest description", "id": "timoboz/my-awesome-dataset", "id_no": 12345, "licenses": [{"name": "CC0-1.0"}], "resources": [ { "path": "my-awesome-data.csv", "description": "This is my awesome data!", "schema": { "fields": [ { "name": "StringField", "description": "String field description", "type": "string" }, { "name": "NumberField", "description": "Number field description", "type": "number" }, { "name": "DateTimeField", "description": "Date time field description", "type": "datetime" } ] } }, { "path": "my-awesome-extra-file.txt", "description": "This is my awesome extra file!" } ], "keywords": [ "beginner", "tutorial" ], "expectedUpdateFrequency": "monthly", "userSpecifiedSources": "World Bank and OECD ([link](http://data.worldbank.org/indicator/NY.GDP.MKTP.CD))", "image": "relative/path/to/new/image.png" } ``` ## Contents The following metadata is currently supported: * `kaggle datasets create` (create a new Dataset): * `title`: Title of the dataset, must be between 6 and 50 characters in length. * `subtitle`: Subtitle of the dataset, must be between 20 and 80 characters in length. * `description`: Description of the dataset. * `id`: The URL slug of your new dataset, a combination of: 1. Your username or organization slug (if you are a member of an organization). 2. A unique Dataset slug, must be between 3 and 50 characters in length. * `licenses`: Must have exactly one entry that specifies the license. Only `name` is evaluated, all other information is ignored. See below for options. * `resources`: Contains an array of files that are being uploaded. (Note - this is not required, nor if included, does it need to include all of the files to be uploaded.): * `path`: File path. * `description`: File description. * `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 * `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): * `subtitle`: Subtitle of the dataset, must be between 20 and 80 characters in length. * `description`: Description of the dataset. * `id`: The URL slug of the dataset you want to update (see above). You must be the owner or otherwise have edit rights for this dataset. One of `id` or `id_no` must be specified. If both are, `id_no` will be preferred. * `id_no`: The ID of the dataset. One of `id` or `id_no` must be specified. You must be the owner or otherwise have edit rights for this dataset. If both are, `id_no` will be preferred. * `resources`: Contains an array of files that are being uploaded. (Note - this is not required, nor if included, does it need to include all of the files to be uploaded.): * `path`: File path. * `description`: File description. * `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 * `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: * `expectedUpdateFrequency`: How often you expect to update your dataset with new versions. See [section below](#expected-update-frequencies) for possible values. * `userSpecifiedSources`: An explanation of the source(s) of your dataset. Most basic markdown features are supported for this string. * `image`: A relative file path to a new image file you want to use for your dataset. The path should be relative to the location of the dataset-metadata.json file. See [section below](#images) for more specifics about file types and expected image size. We will add further metadata processing in upcoming versions of the API. ## Licenses You can specify the following licenses for your datasets: * `CC0-1.0`: [CC0: Public Domain](https://creativecommons.org/publicdomain/zero/1.0/) * `CC-BY-SA-3.0`: [CC BY-SA 3.0](https://creativecommons.org/licenses/by-sa/3.0/) * `CC-BY-SA-4.0`: [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) * `CC-BY-NC-SA-4.0`: [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/) * `GPL-2.0`: [GPL 2](http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html) * `ODbL-1.0`: Database: [Open Database](http://opendatacommons.org/licenses/odbl/1.0/), Contents: © Original Authors * `DbCL-1.0`: Database: [Open Database](http://opendatacommons.org/licenses/odbl/1.0/), Contents: [Database Contents](http://opendatacommons.org/licenses/dbcl/1.0/) * `copyright-authors`: Data files © Original Authors * `other`: Other (specified in description) * `unknown`: Unknown * `CC-BY-4.0`: https://creativecommons.org/licenses/by/4.0/ * `CC-BY-NC-4.0`: https://creativecommons.org/licenses/by-nc/4.0/ * `PDDL`: https://opendatacommons.org/licenses/pddl/1.0/ * `CC-BY-3.0`: https://creativecommons.org/licenses/by/3.0/ * `CC-BY-3.0-IGO`: https://creativecommons.org/licenses/by/3.0/igo/ * `US-Government-Works`: https://www.usa.gov/government-works/ * `CC-BY-NC-SA-3.0-IGO`: https://creativecommons.org/licenses/by-nc-sa/3.0/igo/ * `CDLA-Permissive-1.0`: https://cdla.io/permissive-1-0/ * `CDLA-Sharing-1.0`: https://cdla.io/sharing-1-0/ * `CC-BY-ND-4.0`: https://creativecommons.org/licenses/by-nd/4.0/ * `CC-BY-NC-ND-4.0`: https://creativecommons.org/licenses/by-nc-nd/4.0/ * `ODC-BY-1.0`: https://opendatacommons.org/licenses/by/1-0/index.html * `LGPL-3.0`: http://www.gnu.org/licenses/lgpl-3.0.html * `AGPL-3.0`: http://www.gnu.org/licenses/agpl-3.0.html * `FDL-1.3`: http://www.gnu.org/licenses/fdl-1.3.html * `EU-ODP-Legal-Notice`: https://ec.europa.eu/info/legal-notice_en * `apache-2.0`: https://www.apache.org/licenses/LICENSE-2.0 * `GPL-3.0`: [GPL 2](https://www.gnu.org/licenses/gpl-3.0.html) ## Data types You can specify the following data types * `string` * `boolean` * `numeric` * `datetime` * `id` * `uuid` * `latitude` * `longitude` * `coordinates` * `country` * `province` (these are states in the US) * `postalcode` * `address` * `email` * `url` * `integer` * `decimal` * `city` ## Expected update frequencies You can specify the following values for `expectedUpdateFrequency`: * `not specified` * `never` * `annually` * `quarterly` * `monthly` * `weekly` * `daily` * `hourly` ## Images The recommended way to update your dataset's image is by placing a file named `dataset-cover-image.png` (or `.jpg`, `.jpeg`, `.webp`), as a sibling file to your `datasets-metadata.json`. Example: - `/some/path/dataset-metadata.json` - `/some/path/dataset-cover-image.png` The image file will only be used for dataset metadata, and not be uploaded as a file within your dataset. ### Specifying an image with a relative path As an alternative, you can update your dataset image by providing a relative path from your `datasets-metadata.json` to an image file, using the `image` property. If your files were located at: - `/some/path/dataset-metadata.json` - `/some/path/to/my-image.jpg` This property should be specified as: ``` "image": "to/my-image.jpg" ``` ### Supported image file types and expected dimensions The following file types are supported: * `.png` * `.jpg` * `.jpeg` * `.webp` The image needs to have a minimum width of 560px and a minimum height of 280px. The same image file will be used for two different crops: - Header, 2:1 ratio - Crop rectangle: width: 560px, height: 280px, top: 0, left: 0 - For an image with dimensions 560px x 280px, this will be the entire rectangular image. - Thumbnail, 1:1 ratio - Crop rectangle: width: 280px, height: 280px, top: 0, left: 140px - For an image with dimensions 560px x 280px, this will be a centered 280px square. While you can upload a larger image than 560px x 280px, the crops as specified above will be applied, and this may not look good. These crops can always be edited in the UI on kaggle.com on the settings page for your dataset. --- ### Forums # Forums Commands Commands for browsing and reading Kaggle discussion forums. ## `kaggle forums` Lists all discussion forums. Also available as `kaggle forums list`. **Alias:** `f` **Usage:** ```bash kaggle forums [options] ``` **Options:** * `-v, --csv`: Print results in CSV format. * `-q, --quiet`: Suppress verbose output. **Example:** List all forums in CSV format: ```bash kaggle forums -v ``` **Purpose:** This command helps you discover all available discussion forums on Kaggle. ## `kaggle forums topics list` Lists discussion topics in a forum. **Usage:** ```bash 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., `1`, `product-feedback`). Optional. **Options:** * `--sort-by <SORT_BY>`: Sort order. Valid options: `hot`, `top`, `new`, `recent`, `active`, `relevance`. * `-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. **Example:** List topics in the "getting-started" forum sorted by most recent, showing 5 per page: ```bash kaggle forums topics list getting-started --sort-by recent --page-size 5 ``` **Purpose:** This command lets you browse discussion topics within a specific forum, with filtering and sorting options. ## `kaggle forums topics show` Displays a topic with all comments in tree form (indented). **Usage:** ```bash kaggle forums topics show <TOPIC_REF> [options] ``` **Arguments:** * `<TOPIC_REF>`: A topic reference, which can be: * `<forum-name>/<topic-id>` (e.g., `getting-started/12345`) * `<forum-name> <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:** Show topic 12345 from the "getting-started" forum: ```bash kaggle forums topics show getting-started/12345 ``` Show the same topic using two separate arguments: ```bash kaggle forums topics show getting-started 12345 ``` Show a topic by bare numeric ID: ```bash kaggle forums topics show 12345 ``` **Purpose:** This command displays a full discussion topic along with all of its comments rendered in an indented tree structure. --- ### Index .. _kaggle: .. kaggle-cli documentation master file, created by sphinx-quickstart on Thu Jun 26 22:53:21 2025. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. kaggle-cli documentation ======================== .. toctree:: :maxdepth: 2 :caption: Contents: intro configuration competitions competition_creation datasets kernels models model_instances model_instances_versions benchmarks search tutorials --- ### Kernels # Kernels Commands Commands for interacting with Kaggle Kernels (notebooks and scripts). ## `kaggle kernels list` Lists available kernels. **Usage:** ```bash kaggle kernels list [options] ``` **Options:** * `-m, --mine`: Display only your kernels. * `-p, --page <PAGE>`: Page number for results (default: 1). * `--page-size <SIZE>`: Number of items per page (default: 20). * `-s, --search <SEARCH_TERM>`: Search term. * `-v, --csv`: Print results in CSV format. * `--parent <PARENT_KERNEL>`: Filter by parent kernel (format: `owner/kernel-slug`). * `--competition <COMPETITION_SLUG>`: Filter by competition. * `--dataset <DATASET_SLUG>`: Filter by dataset (format: `owner/dataset-slug`). * `--user <USER>`: Filter by a specific user. * `--language <LANGUAGE>`: Filter by language (`all`, `python`, `r`, `sqlite`, `julia`). * `--kernel-type <TYPE>`: Filter by kernel type (`all`, `script`, `notebook`). * `--output-type <TYPE>`: Filter by output type (`all`, `visualizations`, `data`). * `--sort-by <SORT_BY>`: Sort results (`hotness`, `commentCount`, `dateCreated`, `dateRun`, `relevance`, `scoreAscending`, `scoreDescending`, `viewCount`, `voteCount`). Default: `hotness`. **Examples:** 1. List your own kernels containing "Exercise" in the title, page 2, 5 items per page, in CSV format, sorted by run date: ```bash kaggle kernels list -m -s Exercise --page-size 5 -p 2 -v --sort-by dateRun ``` 2. List kernels that are children of `$KAGGLE_DEVELOPER/exercise-lists` (replace `$KAGGLE_DEVELOPER` with your username): ```bash kaggle kernels list --parent $KAGGLE_DEVELOPER/exercise-lists ``` 3. List the first 5 kernels for the "house-prices-advanced-regression-techniques" competition: ```bash kaggle kernels list --competition house-prices-advanced-regression-techniques --page-size 5 ``` 4. List the first 5 kernels associated with the dataset `dansbecker/home-data-for-ml-course`: ```bash kaggle kernels list --dataset dansbecker/home-data-for-ml-course --page-size 5 ``` 5. List Python notebooks by user `$KAGGLE_DEVELOPER` that output data: ```bash kaggle kernels list --user $KAGGLE_DEVELOPER --language python --kernel-type notebook --output-type data ``` **Purpose:** This command allows you to find kernels based on various filters like ownership, associated competition/dataset, language, or type. ## `kaggle kernels files` Lists output files for a specific kernel. **Usage:** ```bash kaggle kernels files <KERNEL> [options] ``` **Arguments:** * `<KERNEL>`: Kernel URL suffix (format: `owner/kernel-slug`, e.g., `kerneler/sqlite-global-default`). **Options:** * `-v, --csv`: Print results in CSV format. * `--page-token <PAGE_TOKEN>`: Page token for results paging. * `--page-size <PAGE_SIZE>`: Number of items to show on a page (default: 20, max: 200). **Example:** List the first output file for the kernel `kerneler/sqlite-global-default` in CSV format: ```bash kaggle kernels files kerneler/sqlite-global-default -v --page-size=1 ``` **Purpose:** Use this command to view the files generated by a kernel run. ## `kaggle kernels init` Initializes a metadata file (`kernel-metadata.json`) for a new or existing kernel. See [metadata file format](./kernels_metadata.md). **Usage:** ```bash kaggle kernels init -p <FOLDER_PATH> ``` **Options:** * `-p, --path <FOLDER_PATH>`: The path to the folder where the `kernel-metadata.json` file will be created (defaults to the current directory). **Example:** Initialize a kernel metadata file in the `tests/kernel` folder: ```bash kaggle kernels init -p tests/kernel ``` **Purpose:** This command creates a template `kernel-metadata.json` file. You need to edit this file with details like the kernel's title, ID (slug), language, kernel type, and data sources before pushing it to Kaggle. ## `kaggle kernels push` Pushes new code/notebook and metadata to a kernel, then runs the kernel. **Usage:** ```bash kaggle kernels push -p <FOLDER_PATH> [options] ``` **Options:** * `--accelerator <ACCELERATOR_ID>`: ID name of the accelerator to use during the run. E.g. "NvidiaTeslaP100" (aka default GPU), "NvidiaTeslaT4", "TpuV6E8". * `-p, --path <FOLDER_PATH>`: Path to the folder containing the kernel file (e.g., `.ipynb`, `.Rmd`, `.py`) and the `kernel-metadata.json` file (defaults to the current directory). * `-t, --timeout <SECONDS>`: Maximum run time in seconds. **Example:** Push the kernel from the `tests/kernel` folder (assuming it contains the kernel file and `kernel-metadata.json`): ```bash kaggle kernels push -p tests/kernel ``` **Purpose:** This command uploads your local kernel file and its metadata to Kaggle. If the kernel specified in the metadata exists under your account, it will be updated. Otherwise, a new kernel will be created. After uploading, Kaggle will attempt to run the kernel. Accelerators available as of Feb 2026: * NvidiaTeslaP100 * TpuV38 * NvidiaTeslaT4 * NvidiaTeslaT4Highmem * Tpu1VmV38 * NvidiaTeslaA100 * NvidiaL4 * TpuV5E8 * NvidiaL4X1 * TpuV6E8 * NvidiaH100 * NvidiaRtxPro6000 Some of these are only available to participants of specific competitions, and some are only available to Kaggle admins. > [!WARNING] > `NvidiaTeslaP100` is not usable for GPU compute with the default Kaggle image. Its PyTorch build (cu128) does not include Pascal (`sm_60`) kernels, so `torch.cuda.is_available()` returns `True` but the first CUDA operation fails with `cudaErrorNoKernelImageForDevice`. Use `NvidiaTeslaT4` instead, or install a Pascal-compatible torch build if you require a P100. ## `kaggle kernels pull` Pulls down the code/notebook and metadata for a kernel. **Usage:** ```bash kaggle kernels pull <KERNEL> [options] ``` **Arguments:** * `<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:** * `-p, --path <PATH>`: Folder to download files to (defaults to current directory). * `-w, --wp`: Download files to the current working path. * `-m, --metadata`: Generate a `kernel-metadata.json` file along with the kernel code. **Examples:** 1. Pull the kernel `$KAGGLE_DEVELOPER/exercise-as-with` and its metadata into the `tests/kernel` folder: ```bash kaggle kernels pull -p tests/kernel $KAGGLE_DEVELOPER/exercise-as-with -m ``` 2. Pull the kernel `$KAGGLE_DEVELOPER/exercise-as-with` into the current working directory: ```bash 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. ## `kaggle kernels output` Gets the data output from the latest run of a kernel. **Usage:** ```bash kaggle kernels output <KERNEL> [options] ``` **Arguments:** * `<KERNEL>`: Kernel URL suffix (e.g., `kerneler/using-google-bird-vocalization-model`). **Options:** * `-p, --path <PATH>`: Folder to download output files to (defaults to current directory). * `-w, --wp`: Download files to the current working path. * `-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:** Download the output of the kernel `kerneler/using-google-bird-vocalization-model`, forcing overwrite: ```bash kaggle kernels output kerneler/sqlite-global-default -o ``` Download PNG files only: ```bash 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. 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` Displays the status of the latest run of a kernel. **Usage:** ```bash kaggle kernels status <KERNEL> ``` **Arguments:** * `<KERNEL>`: Kernel URL suffix (e.g., `kerneler/sqlite-global-default`). **Example:** Get the status of the kernel `kerneler/sqlite-global-default`: ```bash kaggle kernels status kerneler/sqlite-global-default ``` **Purpose:** This command tells you whether the latest run of your kernel is still running, completed successfully, or failed. ## `kaggle kernels delete` Deletes a kernel from Kaggle. **Usage:** ```bash kaggle kernels delete <KERNEL> [options] ``` **Arguments:** * `<KERNEL>`: Kernel URL suffix (format: `owner/kernel-slug`, e.g., `$KAGGLE_DEVELOPER/exercise-delete`). **Options:** * `-y, --yes`: Automatically confirm deletion without prompting. **Example:** Delete the kernel `$KAGGLE_DEVELOPER/exercise-delete` and automatically confirm: ```bash 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. ## Using Secrets in Kernels If your kernel needs to access sensitive information (like API keys or passwords) without exposing them in your code, you should use **Kaggle Secrets**. ### 1. Define Secrets on Kaggle.com (no CLI support) 1. Open your notebook in the Kaggle Notebook Editor. 2. In the menu, select **Add-ons** -> **Secrets**. 3. Add your secrets as key-value pairs (e.g., Label: `MY_API_KEY`, Value: `your-actual-key-value`). ### 2. Use Secrets in your Code Running on Kaggle.com Use the `UserSecretsClient` from the `kaggle_secrets` package to retrieve your secrets at runtime: ```python from kaggle_secrets import UserSecretsClient # Retrieve the secret value using the label you defined secret_value = UserSecretsClient().get_secret("MY_API_KEY") ``` **Note:** The `kaggle_secrets` package is pre-installed and only functional within the Kaggle notebook execution environment. It will not work when running scripts locally. --- ### Kernels Metadata To upload and run a kernel, a special `kernel-metadata.json` file must be specified. Here's a basic example for `kernel-metadata.json`: ``` { "id": "timoboz/my-awesome-kernel", "id_no": 12345, "title": "My Awesome Kernel", "code_file": "my-awesome-kernel.ipynb", "language": "python", "kernel_type": "notebook", "is_private": "false", "enable_gpu": "false", "enable_internet": "false", "machine_shape": "", "dataset_sources": ["timoboz/my-awesome-dataset"], "competition_sources": [], "kernel_sources": [], "model_sources": [] } ``` You can also use the API command `kaggle kernels init -p /path/to/kernel` to have the API create this file for you for a new kernel. If you wish to get the metadata for an existing kernel, you can use `kaggle kernels pull -p /path/to/download -k username/kernel-slug -m`. ## Contents We currently support the following metadata fields for kernels. * `id`: The URL slug of your kernel. One of `id` or `id_no` must be specified. If both are, `id_no` will be preferred. 1. Your username slug 2. A unique kernel slug * `id_no`: The kernel's numeric ID. One of `id` or `id_no` must be specified. If both are, `id_no` will be preferred. * `title`: The title of the kernel. Required for new kernels - optional for existing ones. Please be aware that kernel titles and slugs are linked to each other. A kernel slug is always the title lowercased with dashes (`-`) replacing spaces. * If you wish to rename your kernel, you may change the title within the metadata. However, you will need to update the `id` as well AFTER the rename is complete. * `code_file`: The path to your kernel source code. Required. If not an absolute path, it should be relative to the location of `kernel-metadata.json`. * `language`: The language your kernel is written in. Valid options are `python`, `r`, and `rmarkdown`. Required. * `kernel_type`: The type of kernel. Valid options are `script` and `notebook`. Required. * `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`). > [!WARNING] > `NvidiaTeslaP100` is not usable with the default Kaggle image. Its PyTorch build (cu128) does not include Pascal (`sm_60`) kernels, so `torch.cuda.is_available()` returns `True` but the first CUDA operation fails with `cudaErrorNoKernelImageForDevice`. Use `NvidiaTeslaT4` instead, or install a Pascal-compatible torch build if you require a P100. * `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"` * `model_sources`: A list of model sources, specified as `"username/model-slug/framework/variation-slug/version-number"` We will add further metadata processing in upcoming versions of the API. --- ### Model Variations # Model Variation Commands Commands for interacting with variations of Kaggle Models. A model variation typically represents a specific framework of a parent model. ## `kaggle models variations init` Initializes a metadata file (`model-instance-metadata.json`) for creating a new model variation. Note that the name of the file reflects the old name for a variation, which was "instance". **Usage:** ```bash kaggle models variations init -p <FOLDER_PATH> ``` **Options:** * `-p, --path <FOLDER_PATH>`: The path to the folder where the `model-instance-metadata.json` file will be created (defaults to the current directory). **Example:** Initialize a model variation metadata file in the `tmp` folder: ```bash kaggle models variations init -p tmp ``` **Purpose:** This command creates a template `model-instance-metadata.json` file. You must edit this file with details such as the owner slug, the parent model slug, the variation (or instance) slug (URL-friendly name for this variations), and the framework (e.g., `tensorflow`, `pytorch`, `jax`, `sklearn`) before creating the variation. ## `kaggle models variations create` Creates a new model variation under an existing model on Kaggle. **Usage:** ```bash kaggle models variations create -p <FOLDER_PATH> [options] ``` **Options:** * `-p, --path <FOLDER_PATH>`: Path to the folder containing the model variation files and the `model-instance-metadata.json` file (defaults to the current directory). * `-q, --quiet`: Suppress verbose output. * `-r, --dir-mode <MODE>`: How to handle directories within the upload: `skip` (ignore), `zip` (compressed upload), `tar` (uncompressed upload) (default: `skip`). * `--ignore-patterns <PATTERNS>`: Patterns of files/dirs to ignore. Can be specified multiple times. **Example:** Create a new model variation using the metadata and files in the `tmp` folder, quietly, skipping subdirectories. (Assumes `model-instance-metadata.json` in `tmp` has been properly edited): ```bash # Example: Edit model-instance-metadata.json first # sed -i 's/INSERT_OWNER_SLUG_HERE/your-username/' tmp/model-instance-metadata.json # sed -i 's/INSERT_EXISTING_MODEL_SLUG_HERE/parent-model-slug/' tmp/model-instance-metadata.json # sed -i 's/INSERT_INSTANCE_SLUG_HERE/my-variation-slug/' tmp/model-instance-metadata.json # sed -i 's/INSERT_FRAMEWORK_HERE/jax/' tmp/model-instance-metadata.json # echo "a,b,c,d" > tmp/data.csv # Example model file kaggle models variations create -p tmp -q -r skip ``` **Purpose:** This command uploads your local model files (e.g., weights, architecture definition) and the associated variation metadata to create a new variation under a specified parent model on Kaggle. This effectively creates the first version of this model variation. ## `kaggle models variations get` Downloads the `model-instance-metadata.json` file for an existing model variation. **Usage:** ```bash kaggle models variations get <MODEL_VARIATION> -p <FOLDER_PATH> ``` **Arguments:** * `<MODEL_VARIATION>`: Model variation URL suffix in the format `owner/model-slug/framework/variation-slug` (e.g., `$KAGGLE_DEVELOPER/test-model/jax/main`). **Options:** * `-p, --path <FOLDER_PATH>`: Folder to download the `model-instance-metadata.json` file to. **Example:** Download the metadata for model variation `$KAGGLE_DEVELOPER/test-model/jax/main` into the `tmp` folder: ```bash kaggle models variations get $KAGGLE_DEVELOPER/test-model/jax/main -p tmp ``` **Purpose:** This command retrieves the metadata file for an existing model variation. This can be useful for inspection or as a basis for an update. ## `kaggle models variations files` Lists files for the current version of a model variation. **Usage:** ```bash kaggle models variations files <MODEL_VARIATION> [options] ``` **Arguments:** * `<MODEL_VARIATION>`: Model variation URL suffix (e.g., `$KAGGLE_DEVELOPER/test-model/jax/main`). **Options:** * `-v, --csv`: Print results in CSV format. * `--page-size <SIZE>`: Number of items per page (default: 20). * `--page-token <TOKEN>`: Page token for results paging. **Example:** List the first 5 files for the model variation `$KAGGLE_DEVELOPER/test-model/jax/main` in CSV format: ```bash kaggle models variations files $KAGGLE_DEVELOPER/test-model/jax/main -v --page-size 5 ``` **Purpose:** Use this command to see the files associated with the latest version of a specific model variation. ## `kaggle models variations update` Updates an existing model variation on Kaggle using a local `model-instance-metadata.json` file. **Usage:** ```bash kaggle models variations update -p <FOLDER_PATH> ``` **Options:** * `-p, --path <FOLDER_PATH>`: Path to the folder containing the `model-instance-metadata.json` file with the updated information (defaults to the current directory). Note: This command only updates the metadata of the variation, not the files. To update files, create a new version. **Example:** Update the model variation whose details are in `tmp/model-instance-metadata.json` (ensure the slugs and owner in the JSON match an existing model variation): ```bash kaggle models variations update -p tmp ``` **Purpose:** Use this command to change the metadata of an existing model variation, such as its description or other fields defined in the `model-instance-metadata.json` file. This does not upload new files or create a new version. ## `kaggle models variations delete` Deletes a model variation from Kaggle. **Usage:** ```bash kaggle models variations delete <MODEL_VARIATION> [options] ``` **Arguments:** * `<MODEL_VARIATION>`: Model variation URL suffix in the format `owner/model-slug/framework/variation-slug` (e.g., `$KAGGLE_DEVELOPER/test-model/jax/main`). **Options:** * `-y, --yes`: Automatically confirm deletion without prompting. **Example:** Delete the model variation `$KAGGLE_DEVELOPER/test-model/jax/main` and automatically confirm: ```bash kaggle models variations delete $KAGGLE_DEVELOPER/test-model/jax/main -y ``` **Purpose:** This command permanently removes one of your model variations (and all its versions) from Kaggle. Use with caution. --- ### Model Variations Versions # Model Variation Versions Commands Commands for managing versions of a specific Kaggle Model Variation. Each version represents a snapshot of the model variation files at a point in time. ## `kaggle models variations versions create` Creates a new version of an existing model variation. **Usage:** ```bash kaggle models variations versions create <MODEL_VARIATION> -p <FOLDER_PATH> [options] ``` **Arguments:** * `<MODEL_VARIATION>`: The target model variation URL suffix for the new version (format: `owner/model-slug/framework/variation-slug`, e.g., `$KAGGLE_DEVELOPER/test-model/jax/main`). **Options:** * `-p, --path <FOLDER_PATH>`: Path to the folder containing the files for this new version (defaults to the current directory). * `-n, --version-notes <NOTES>`: Notes describing this version. * `-q, --quiet`: Suppress verbose output. * `-r, --dir-mode <MODE>`: How to handle directories within the upload: `skip` (ignore), `zip` (compressed upload), `tar` (uncompressed upload) (default: `skip`). * `--ignore-patterns <PATTERNS>`: Patterns of files/dirs to ignore. Can be specified multiple times. **Example:** Create a new version for the model variation `$KAGGLE_DEVELOPER/test-model/jax/main` using files from the `tmp` folder, with version notes "Updated model files", quietly, and skipping subdirectories: ```bash # Ensure tmp folder contains the new files for the version, e.g., data_v2.csv # echo "e,f,g,h" > tmp/data_v2.csv kaggle models variations versions create $KAGGLE_DEVELOPER/test-model/jax/main -p tmp -n "Updated model files" -q -r skip ``` **Purpose:** This command uploads a new set of files to an existing model variation, creating a new, numbered version. This allows you to track changes and revert to previous versions of your model variation files. ## `kaggle models variations versions download` Downloads files for a specific version of a model variation. **Usage:** ```bash kaggle models variations versions download <MODEL_VARIATION_VERSION> [options] ``` **Arguments:** * `<MODEL_VARIATION_VERSION>`: Model variation version URL suffix in the format `owner/model-slug/framework/variation-slug/version-number` (e.g., `$KAGGLE_DEVELOPER/test-model/jax/main/1`). **Options:** * `-p, --path <PATH>`: Folder to download files to (defaults to current directory). * `--untar`: Untar the downloaded file if it's a `.tar` archive (deletes the `.tar` file afterwards). * `--unzip`: Unzip the downloaded file if it's a `.zip` archive (deletes the `.zip` file afterwards). * `-f, --force`: Force download, overwriting existing files. * `-q, --quiet`: Suppress verbose output. **Example:** Download version 1 of the model variation `$KAGGLE_DEVELOPER/test-model/jax/main` into the `tmp` folder, untar if applicable, force overwrite, and do it quietly: ```bash kaggle models variations versions download $KAGGLE_DEVELOPER/test-model/jax/main/1 -p tmp -q -f --untar ``` **Purpose:** This command allows you to retrieve the specific files associated with a particular version of a model variation. ## `kaggle models variations versions files` Lists files for a specific version of a model variation. **Usage:** ```bash kaggle models variations versions files <MODEL_VARIATION_VERSION> [options] ``` **Arguments:** * `<MODEL_VARIATION_VERSION>`: Model variation version URL suffix (e.g., `google/gemma/pytorch/7b/2`). **Options:** * `-v, --csv`: Print results in CSV format. * `--page-size <SIZE>`: Number of items per page (default: 20). * `--page-token <TOKEN>`: Page token for results paging. **Example:** List the first 3 files for version 2 of the model variation `google/gemma/pytorch/7b` in CSV format: ```bash kaggle models variations versions files google/gemma/pytorch/7b/2 -v --page-size=3 ``` **Purpose:** Use this command to see the individual files that constitute a specific version of a model variation before downloading. ## `kaggle models variations versions delete` Deletes a specific version of a model variation from Kaggle. **Usage:** ```bash kaggle models variations versions delete <MODEL_VARIATION_VERSION> [options] ``` **Arguments:** * `<MODEL_VARIATION_VERSION>`: Model variation version URL suffix in the format `owner/model-slug/framework/variation-slug/version-number` (e.g., `$KAGGLE_DEVELOPER/test-model/jax/main/1`). **Options:** * `-y, --yes`: Automatically confirm deletion without prompting. **Example:** Delete version 1 of the model variation `$KAGGLE_DEVELOPER/test-model/jax/main` and automatically confirm: ```bash kaggle models variations versions delete $KAGGLE_DEVELOPER/test-model/jax/main/1 -y ``` **Purpose:** This command permanently removes a specific version of your model variation from Kaggle. Use with caution. If it's the only version, this may lead to the deletion of the model variation itself if no other versions exist. --- ### Models # Models Commands Commands for interacting with Kaggle Models. ## `kaggle models list` Lists available models. **Usage:** ```bash kaggle models list [options] ``` **Options:** * `--owner <OWNER>`: Filter by a specific user or organization. * `--sort-by <SORT_BY>`: Sort results. Valid options: `hotness`, `downloadCount`, `voteCount`, `notebookCount`, `createTime` (default: `hotness`). * `-s, --search <SEARCH_TERM>`: Search term. * `--page-size <SIZE>`: Number of items per page (default: 20). * `--page-token <TOKEN>`: Page token for results paging. * `-v, --csv`: Print results in CSV format. **Examples:** 1. List models owned by `$KAGGLE_DEVELOPER` (replace with your username), sorted by creation time, in CSV format: ```bash kaggle models list --owner $KAGGLE_DEVELOPER --sort-by createTime -v ``` 2. List the first 5 models matching the search term "gemini": ```bash kaggle models list -s gemini --page-size 5 ``` **Purpose:** This command helps you find models on Kaggle, filtering by owner or searching by keywords, and sorting by various criteria. ## `kaggle models init` Initializes a metadata file (`model-metadata.json`) for creating a new model. See [metadata file format](./models_metadata.md). **Usage:** ```bash kaggle models init -p <FOLDER_PATH> ``` **Options:** * `-p, --path <FOLDER_PATH>`: The path to the folder where the `model-metadata.json` file will be created (defaults to the current directory). **Example:** Initialize a model metadata file in a new temporary folder `tmp`: ```bash mkdir tmp kaggle models init -p tmp ``` **Purpose:** This command creates a template `model-metadata.json` file. You must edit this file with your model's details, such as owner slug, title, model slug (URL-friendly version of the title), and a description, before creating the model on Kaggle. ## `kaggle models create` Creates a new model on Kaggle. **Usage:** ```bash kaggle models create -p <FOLDER_PATH> ``` **Options:** * `-p, --path <FOLDER_PATH>`: Path to the folder containing the `model-metadata.json` file (defaults to the current directory). This folder should also contain your model files that you intend to upload as part of the first model variation. **Example:** Create a new model using the metadata in `tmp/model-metadata.json`. (Assumes the metadata file has been edited with owner, title, and slug): ```bash # Example: Edit model-metadata.json first # sed -i 's/INSERT_OWNER_SLUG_HERE/your-username/' tmp/model-metadata.json # sed -i 's/INSERT_TITLE_HERE/My Awesome Model/' tmp/model-metadata.json # sed -i 's/INSERT_SLUG_HERE/my-awesome-model/' tmp/model-metadata.json kaggle models create -p tmp ``` **Purpose:** This command registers a new model on Kaggle using the provided metadata. After this, you will typically create model variations and versions. ## `kaggle models get` Downloads the `model-metadata.json` file for an existing model. **Usage:** ```bash kaggle models get <MODEL> -p <FOLDER_PATH> ``` **Arguments:** * `<MODEL>`: Model URL suffix in the format `owner/model-slug` (e.g., `$KAGGLE_DEVELOPER/test-model`). **Options:** * `-p, --path <FOLDER_PATH>`: Folder to download the `model-metadata.json` file to. **Example:** Download the metadata for model `$KAGGLE_DEVELOPER/test-model` into the `tmp` folder: ```bash kaggle models get -p tmp $KAGGLE_DEVELOPER/test-model ``` **Purpose:** This command retrieves the metadata file for an existing model, which can be useful for inspection or as a basis for an update. ## `kaggle models update` Updates an existing model on Kaggle using a local `model-metadata.json` file. **Usage:** ```bash kaggle models update -p <FOLDER_PATH> ``` **Options:** * `-p, --path <FOLDER_PATH>`: Path to the folder containing the `model-metadata.json` file with the updated information (defaults to the current directory). **Example:** Update the model whose details are in `tmp/model-metadata.json` (ensure the slug and owner in the JSON match an existing model): ```bash kaggle models update -p tmp ``` **Purpose:** Use this command to change the metadata of an existing model, such as its title, description, or other fields defined in the `model-metadata.json` file. ## `kaggle models delete` Deletes a model from Kaggle. **Usage:** ```bash kaggle models delete <MODEL> [options] ``` **Arguments:** * `<MODEL>`: Model URL suffix in the format `owner/model-slug` (e.g., `$KAGGLE_DEVELOPER/test-model`). **Options:** * `-y, --yes`: Automatically confirm deletion without prompting. **Example:** Delete the model `$KAGGLE_DEVELOPER/test-model` and automatically confirm: ```bash kaggle models delete $KAGGLE_DEVELOPER/test-model -y ``` **Purpose:** This command permanently removes one of your models (and all its variations and versions) from Kaggle. Use with caution. ## `kaggle models topics list` Lists discussion topics for a model. **Usage:** ```bash kaggle models topics list <MODEL> [options] ``` **Arguments:** * `<MODEL>`: Model ref in format `<owner>/<model-slug>` (e.g., `google/gemma`). **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:** ```bash kaggle models topics list google/gemma --sort-by hot ``` **Purpose:** This command lets you browse discussion topics for a specific model. ## `kaggle models topics show` Displays a model discussion topic with all comments in tree form. **Usage:** ```bash kaggle models topics show <TOPIC_REF> [options] ``` **Arguments:** * `<TOPIC_REF>`: A topic reference, which can be: * `<model>/<topic-id>` (e.g., `google/gemma/12345` - note that this supports multi-slash model slugs) * `<model> <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 models topics show google/gemma/12345 ``` **Purpose:** This command displays a full discussion topic along with all of its comments rendered in an indented tree structure. --- ### Models Metadata A full model is composed of 3 types of entities: 1. The model 2. The variations 3. The variation versions Let's take the example of [efficientnet](https://www.kaggle.com/models/tensorflow/efficientnet) to explain these entities. A model like `efficientnet` contains multiple variations. A variation is a specific variation of the model (e.g. B0, B1, ...) with a certain framework (e.g. TensorFlow2). ## Model To create a model, a special `model-metadata.json` file must be specified. Here's a basic example for `model-metadata.json`: ``` { "ownerSlug": "INSERT_OWNER_SLUG_HERE", "title": "INSERT_TITLE_HERE", "slug": "INSERT_SLUG_HERE", "subtitle": "", "isPrivate": true, "description": "Model Card Markdown, see below", "publishTime": "", "provenanceSources": "" } ``` You can also use the API command `kaggle models init -p /path/to/model` to have the API create this file for you for a new model. If you wish to get the metadata for an existing model, you can use `kaggle models get username/model-slug`. ### Contents We currently support the following metadata fields for models. * `ownerSlug`: the slug of the user or organization * `title`: the model's title * `slug`: the model's slug (unique per owner) * `licenseName`: the name of the license (see the list below) * `subtitle`: the model's subtitle * `isPrivate`: whether or not the model should be private (only visible by the owners). If not specified, will be `true` * `description`: the model's card in markdown syntax (see the template below) * `publishTime`: the original publishing time of the model * `provenanceSources`: the provenance of the model ## Model Variation To create a model variation, a special `model-instance-metadata.json` file must be specified. Here's a basic example for `model-instance-metadata.json`: ``` { "ownerSlug": "INSERT_OWNER_SLUG_HERE", "modelSlug": "INSERT_EXISTING_MODEL_SLUG_HERE", "instanceSlug": "INSERT_INSTANCE_SLUG_HERE", "framework": "INSERT_FRAMEWORK_HERE", "overview": "", "usage": "Usage Markdown, see below", "licenseName": "Apache 2.0", "fineTunable": False, "trainingData": [], "modelInstanceType": "Unspecified", "baseModelInstance": "", "externalBaseModelUrl": "" } ``` You can also use the API command `kaggle models variations init -p /path/to/model-variation` to have the API create this file for you for a new model variation. ### Contents We currently support the following metadata fields for model variations. * `ownerSlug`: the slug of the user or organization of the model * `modelSlug`: the existing model's slug * `instanceSlug`: the slug of the variation * `framework`: the variation's framework (possible options: `tensorFlow1`,`tensorFlow2`,`tfLite`,`tfJs`,`pyTorch`,`jax`,`coral`, ...) * `overview`: a short overview of the variation * `usage`: the variation's usage in markdown syntax (see the template below) * `fineTunable`: whether the variation is fine tunable * `trainingData`: a list of training data in the form of strings, URLs, Kaggle Datasets, etc... * `modelInstanceType`: whether the model variation is a base model, external variant, internal variant, or unspecified * `baseModelInstance`: if this is an internal variant, the `{owner-slug}/{model-slug}/{framework}/{variation-slug}` of the base model variation * `externalBaseModelUrl`: if this is an external variant, a URL to the base model ### Licenses Here is a list of the available licenses for models: - Apache 2.0 - Attribution 3.0 IGO (CC BY 3.0 IGO) - Attribution 3.0 Unported (CC BY 3.0) - Attribution 4.0 International (CC BY 4.0) - Attribution-NoDerivatives 4.0 International (CC BY-ND 4.0) - Attribution-NonCommercial 4.0 International (CC BY-NC 4.0) - Attribution-NonCommercial-NoDerivatives 4.0 International (CC BY-NC-ND 4.0) - Attribution-NonCommercial-ShareAlike 3.0 IGO (CC BY-NC-SA 3.0 IGO) - BSD-3-Clause - CC BY-NC-SA 4.0 - CC BY-SA 3.0 - CC BY-SA 4.0 - CC0: Public Domain - Community Data License Agreement - Permissive - Version 1.0 - Community Data License Agreement - Sharing - Version 1.0 - GNU Affero General Public License 3.0 - GNU Free Documentation License 1.3 - GNU Lesser General Public License 3.0 - GPL 2 - MIT - ODC Attribution License (ODC-By) - ODC Public Domain Dedication and Licence (PDDL) - GPL 3 ### Usage The following template variables can be used in this markdown: - `${VERSION_NUMBER}` is replaced by the version number when rendered - `${VARIATION_SLUG}` is replaced by the variation slug when rendered - `${FRAMEWORK}` is replaced by the framework name - `${PATH}` is replaced by `/kaggle/input/<model_slug>/<framework>/<variation_slug>/<version>`. - `${FILEPATH}` is replaced by `/kaggle/input/<model_slug>/<framework>/<variation_slug>/<version>/<filename>`. This value is only defined if the databundle contain a single file - `${URL}` is replaced by the absolute URL of the model --- ### Output Format # 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` --- ### README # Kaggle CLI Documentation Welcome to the Kaggle CLI documentation. This guide provides detailed information on how to use the Kaggle command-line interface to interact with Kaggle's platform. ## Installation Note: Ensure you have Python 3.11+ and the package manager `pip` installed. Install the `kaggle` package with [pip](https://pypi.org/project/pip/): ```sh pip install kaggle ``` If you run into a `Command kaggle not found` error, ensure that your Python executable scripts are in your $PATH. For a local user install on Linux, the default location is `~/.local/bin`. On Windows, the default location is `$PYTHON_HOME/Scripts`. ## Authentication First, you will need a Kaggle account. You can sign up [here](https://www.kaggle.com/account/login). After login, you can download your Kaggle API credentials at https://www.kaggle.com/settings/api by clicking on the "Generate New Token" button under the "API" section. ### Option 1: OAuth Obtains access credentials for your Kaggle user accounts via a web-based authrorization flow. ```sh kaggle auth login ``` ### Option 2: Environment variable ```sh export KAGGLE_API_TOKEN=xxxxxxxxxxxxxx # Copied from the settings UI ``` ### Option 3: API token file Store your Kaggle API token obtained from your [Kaggle account API tokens settings page](https://www.kaggle.com/settings/api) in a file at `~/.kaggle/access_token`. ### Option 4: Legacy API credentials file From your [Kaggle account API tokens settings page](https://www.kaggle.com/settings/api), under "Legacy API Credentials", click on the "Create Legacy API Key" button to generate a `kaggle.json` file and store it at `~/.kaggle/kaggle.json`. ## CLI Usage Run the following command to list the available commands: ```sh kaggle --help ``` The Kaggle CLI is organized into several command groups: * [Competitions](./competitions.md): Manage and participate in Kaggle competitions. * [Datasets](./datasets.md): Search, download, and manage Kaggle datasets. * [Forums](./forums.md): Browse and read Kaggle discussion forums. * [Kernels](./kernels.md): Interact with Kaggle Kernels (notebooks and scripts). Includes information on using [Kaggle Secrets](./kernels.md#using-secrets-in-kernels). * [Models](./models.md): Manage your Kaggle Models. * [Model Variations](./model_variations.md): Manage variations of your Kaggle Models. * [Model Variation Versions](./model_variations_versions.md): Manage versions of your Kaggle Model Variations. * [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: * [Tutorials](./tutorials.md) * [Create a Dataset](./tutorials.md#tutorial-create-a-dataset) * [Find and Download a Dataset](./tutorials.md#tutorial-find-and-download-a-dataset) * [Create a Model](./tutorials.md#tutorial-create-a-model) * [Create a Model Variation](./tutorials.md#tutorial-create-a-model-variation) * [Create a Model Variation Version](./tutorials.md#tutorial-create-a-model-variation-version) * [How to Submit to a Competition](./tutorials.md#tutorial-how-to-submit-to-a-competition) * [How to Submit to a Code Competition](./tutorials.md#tutorial-how-to-submit-to-a-code-competition) --- ### Search # 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> ``` --- ### Simulation Competitions # Tutorial: Simulation Competitions This tutorial walks you through interacting with a Kaggle simulation competition using the CLI — from finding the competition to downloading episode replays and agent logs. Simulation competitions (e.g., [Connect X](https://www.kaggle.com/competitions/connectx), [Lux AI](https://www.kaggle.com/competitions/lux-ai-season-3)) differ from standard competitions. Instead of submitting a CSV of predictions, you submit an agent (code) that plays against other agents in episodes. Each episode contains multiple agents competing against each other. You can identify simulation competitions on the [competitions page](https://www.kaggle.com/competitions) by their "Simulation" tag, or by looking for competitions that mention agents, bots, or game environments in their description. ## 1. Find and Inspect the Competition Search for simulation competitions by keyword: ```bash kaggle competitions list -s simulation ``` Once you've identified a competition (e.g., `connectx`), view its pages to read the rules, evaluation criteria, and other details: ```bash kaggle competitions pages connectx ``` This lists the available pages (e.g., `description`, `rules`, `evaluation`, `data-description`). To read the full content of a page: ```bash kaggle competitions pages connectx --content ``` You can also browse the competition's discussion forum to see what other participants are talking about — top strategies, common pitfalls, environment quirks. List the topics with: ```bash kaggle competitions topics list connectx ``` This prints a table of topics with `id`, `title`, `authorName`, `commentCount`, `votes`, and `postDate`. Sort and paginate with `-s/--sort-by` (one of `hot`, `top`, `new`, `recent`, `active`, `relevance`) and `--page-size`: ```bash kaggle competitions topics list connectx -s top --page-size 10 ``` To read the full discussion under a topic, use the `show` subcommand: ```bash kaggle competitions topics show connectx 12345 ``` This returns the topic content and all its comments rendered in an indented tree structure. ``` ## 2. Accept the Competition Rules Before you can submit or download data, you **must** accept the competition rules on the Kaggle website. Navigate to the competition page (e.g., `https://www.kaggle.com/competitions/connectx`) and click "Join Competition" or "I Understand and Accept". You can verify you've joined by checking your entered competitions: ```bash kaggle competitions list --group entered ``` ## 3. Download Competition Data Download the competition's starter kit and any provided data: ```bash kaggle competitions download connectx -p connectx-data ``` ## 4. Submit Your Agent Simulation competitions require you to submit agent code. You can upload files directly from your local machine. **Single file agent** — if your agent is a single `main.py`: ```bash kaggle competitions submit connectx -f main.py -m "Single file agent v1" ``` **Multi-file agent** — if your agent spans multiple files, bundle them into a `submission.tar.gz` with `main.py` at the root: ```bash tar -czf submission.tar.gz main.py helper.py model_weights.pkl kaggle competitions submit connectx -f submission.tar.gz -m "Multi-file agent v1" ``` **Notebook submission** — alternatively, you can submit via an existing Kaggle notebook: ```bash kaggle competitions submit connectx -k YOUR_USERNAME/connectx-agent -f submission.tar.gz -v 1 -m "Notebook agent v1" ``` ## 5. Monitor Your Submission Check the status of your submissions: ```bash kaggle competitions submissions connectx ``` Note the submission ID from the output — you'll need it to view episodes. ## 6. List Episodes for a Submission Once your submission has played some games, list the episodes: ```bash kaggle competitions episodes 12345678 ``` Replace `12345678` with your submission ID. This shows a table of episodes with columns: `id`, `createTime`, `endTime`, `state`, and `type`. To get the output in CSV format for scripting: ```bash kaggle competitions episodes 12345678 -v ``` ## 7. Download an Episode Replay To download the replay data for a specific episode (useful for visualizing what happened): ```bash kaggle competitions replay 98765432 ``` This downloads the replay JSON to your current directory as `episode-98765432-replay.json`. To specify a download location: ```bash kaggle competitions replay 98765432 -p ./replays ``` ## 8. Download Agent Logs To debug your agent's behavior, download the logs for a specific agent in an episode. You need the episode ID and the agent's index (0-based): ```bash # Download logs for the first agent (index 0) kaggle competitions logs 98765432 0 # Download logs for the second agent (index 1) kaggle competitions logs 98765432 1 -p ./logs ``` This downloads the log file as `episode-98765432-agent-0-logs.json`. ## 9. Inspect Top Teams' Active Agents You can study how the leading teams' agents are performing — useful for scouting strategies or understanding the metagame. Start from the leaderboard to grab the team ID: ```bash kaggle competitions leaderboard connectx -s ``` This prints a table with columns `teamId`, `teamName`, `submissionDate`, `score`. Take the `teamId` of the team you want to inspect (e.g., first place), then list every active submission they have on the leaderboard: ```bash kaggle competitions team-submissions 42 ``` This returns the team's public-safe submissions — `id`, `dateSubmitted`, and `publicScore`. For simulation competitions every leaderboard-eligible submission is listed (not just the best one), so you can see the full rotation of agents a top team is fielding. Pick the submission with the highest `publicScore` and list its episodes, just like you would for your own: ```bash kaggle competitions episodes 98765432 ``` From there you can pull replays and agent logs for any episode that submission played in (`kaggle competitions replay <episode_id>` / `kaggle competitions logs <episode_id> <agent_index>`). ## Putting It All Together Here's a typical workflow for iterating on a simulation competition agent: ```bash # Download competition data kaggle competitions download connectx -p connectx-data # Skim discussion topics for tips before iterating kaggle competitions topics connectx -s top kaggle competitions topic-messages connectx <topic-id> # Submit your agent (single file) kaggle competitions submit connectx -f main.py -m "v1" # Check submission status kaggle competitions submissions connectx # List episodes (replace with your submission ID) kaggle competitions episodes 12345678 # Download replay and logs for an episode kaggle competitions replay 98765432 kaggle competitions logs 98765432 0 # Check the leaderboard kaggle competitions leaderboard connectx -s # Scout the leader: list their active agents, then pick the best one's episodes kaggle competitions team-submissions <leader-team-id> kaggle competitions episodes <best-submission-id> ``` --- ### Tutorials # Kaggle CLI Tutorials These tutorials illustrate how to use a sequence of Kaggle CLI commands to accomplish common tasks. ## Introduction Before starting these tutorials, please make sure you have: 1. Installed the Kaggle CLI, following the instructions [here](./README.md#installation). 2. Set up your API credentials, following the instructions [here](./README.md#authentication) 3. Logged in to Kaggle in a web browser. This will allow you to verify the results of the CLI commands in the [`Your Work`](https://www.kaggle.com/work) section of your Kaggle profile. ## Tutorial: Create a Dataset This tutorial walks you through creating a new dataset on Kaggle. 1. **Start from an empty directory.** Create a new directory for your dataset files and navigate into it. ```bash mkdir my-new-dataset cd my-new-dataset ``` 2. **Create a sample data file.** For this example, create a CSV file named `sample_data.csv` with an index column and three random data columns, and a few rows of data. ```bash echo "id,col_a,col_b,col_c" > sample_data.csv echo "1,0.5,0.2,0.8" >> sample_data.csv echo "2,0.1,0.7,0.3" >> sample_data.csv echo "3,0.9,0.4,0.6" >> sample_data.csv ``` 3. **Initialize dataset metadata.** This creates a `dataset-metadata.json` file in your current directory. ```bash kaggle datasets init ``` 4. **Edit the metadata file.** Open `dataset-metadata.json` in a text editor and make the following changes: * Replace `"INSERT_TITLE_HERE"` with your desired dataset title, e.g., `"My Sample Dataset"`. * Replace `"INSERT_SLUG_HERE"` with a URL-friendly version of your title, e.g., `"my-sample-dataset"`. The URL-friendly version is made by converting the title to lower-case and changing spaces to dashes. * You can also add licenses, descriptions, and other relevant information. 5. **Create the dataset.** This command uploads your `sample_data.csv` and `dataset-metadata.json` to Kaggle. ```bash kaggle datasets create -p . ``` You can add `--public` to make it public immediately. 6. **Verify on Kaggle.com.** Refresh the [`Datasets` tab in `Your Work`](https://www.kaggle.com/work/datasets). You should see "My Sample Dataset". ## Tutorial: Find and Download a Dataset This tutorial explains how to find and download using the CLI. 1. **Search for a Dataset (Optional).** * If you know the dataset you want, you can skip this step. Otherwise, you can search for datasets. For example, to search for datasets related to "iris": ```bash kaggle datasets list -s iris ``` * This command will list datasets matching your search query. Note the dataset's "id" (e.g., `uciml/iris`) which you'll use for downloading. 2. **Choose a Dataset and Create a Directory.** * For this tutorial, we'll use the classic "Iris" dataset, which has the id `uciml/iris`. * Create a new directory for your dataset and navigate into it: ```bash mkdir iris-dataset-analysis cd iris-dataset-analysis ``` 3. **Download the Dataset.** * Use the `kaggle datasets download` command with the dataset's id. ```bash kaggle datasets download -d uciml/iris ``` * This will download the dataset files, typically as a ZIP archive (e.g., `iris.zip`), into your current directory (`iris-dataset-analysis`). 4. **Unzip the Dataset.** * Note: you could skip this step by using the `--unzip` flag on the previous command. * Most datasets are downloaded as ZIP files. You'll need to unzip the archive to access the data files (e.g., CSV files). ```bash # Make sure you have unzip installed, or use your OS's GUI to extract # The actual zip file name might vary based on the dataset. # For uciml/iris, it's iris.zip unzip iris.zip ``` 5. **Verify the results.** * After unzipping, you should see the data files (e.g., `Iris.csv`, `database.sqlite`). ## Tutorial: Update a Kernel (Notebook) This tutorial shows how to download an existing kernel, modify it, and push the changes back to Kaggle. 1. **Create or identify a kernel on Kaggle.com.** * Log in to kaggle.com. * Find an existing notebook you own (or create one). For this tutorial, let's assume its title is "My CLI Test Kernel". * Note the kernel slug from the browser's address bar. It will be something like `YOUR_USERNAME/my-cli-test-kernel`. 2. **Create a new local directory for your kernel.** ```bash mkdir my-kernel-project cd my-kernel-project ``` 3. **Pull the kernel.** Use the `kaggle kernels pull` command with your username and the kernel slug. The `-m` flag includes the `kernel-metadata.json` file, which is required for pushing updates. ```bash # Replace YOUR_USERNAME with your actual Kaggle username kaggle kernels pull YOUR_USERNAME/my-cli-test-kernel -m ``` This will download `my-cli-test-kernel.ipynb` (or `.py`/`.Rmd`) and `kernel-metadata.json`. 4. **Edit the kernel or metadata.** * Open the downloaded notebook file (e.g., `my-cli-test-kernel.ipynb`) and make some changes to the code or content. * Open `kernel-metadata.json`. Let's add "benchmark" to the keywords. Find the `"keywords": []` line and change it to `"keywords": ["benchmark"]`. * *Note: While you can edit keywords here, it's often best to manage them on kaggle.com, as there is a restricted list of allowed keywords.* 5. **Push the kernel.** This uploads your changes and the updated metadata, then runs the kernel on Kaggle. ```bash kaggle kernels push -p . ``` 6. **Verify on Kaggle.com.** Refresh the [`Code` tab in `Your Work`](https://www.kaggle.com/work/code). You should see your code changes and the "benchmark" tag added to the kernel settings. ## Tutorial: Create a Model This tutorial guides you through creating a new model on Kaggle. 1. **Start from an empty directory.** Create a new directory for your model files and navigate into it. ```bash mkdir my-new-model cd my-new-model ``` 2. **Copy your model definition files (optional for this step).** If you have files that define your model (e.g., Python scripts, model weights), copy them into this directory. For the `kaggle models create` step, only the metadata is strictly required, but you'll need files when you create a model variation. 3. **Initialize model metadata.** This creates a `model-metadata.json` file. ```bash kaggle models init ``` 4. **Edit the metadata file.** Open `model-metadata.json` and make the following changes: * Replace `"INSERT_OWNER_SLUG_HERE"` with your Kaggle username (e.g., `"YOUR_USERNAME"`). * Replace `"INSERT_TITLE_HERE"` with your model's title (e.g., `"My Awesome AI Model"`). * Replace `"INSERT_SLUG_HERE"` with a URL-friendly version of the title (e.g., `"my-awesome-ai-model"`). * Fill out the `"description"` field and other relevant sections like `"licenses"`. 5. **Create the model.** ```bash kaggle models create -p . ``` 6. **Verify on Kaggle.com.** Refresh the [`Models` tab in `Your Work`](https://www.kaggle.com/work/models). You should see "My Awesome AI Model". ## Tutorial: Create a Model Variation This tutorial shows how to create a variation under an existing model. A model variation usually represents the model implemented in a specific framework (like TensorFlow, PyTorch, JAX, etc.) and includes the actual model files. 1. **Ensure you have a parent model.** Follow the "Create a Model" tutorial if you haven't already. Let's assume your model slug is `my-awesome-ai-model` and your username is `YOUR_USERNAME`. 2. **Prepare your model variation files.** In your model directory (e.g., `my-new-model`), create or place the files for this specific variation. For example, a JAX model might have a `flax_model.params` file. ```bash # In the my-new-model directory echo "This is a placeholder for JAX model parameters" > flax_model.params ``` 3. **Initialize model variation metadata.** This creates `model-instance-metadata.json`. ```bash # Still in the my-new-model directory kaggle models variations init ``` 4. **Edit the variation metadata file.** Open `model-instance-metadata.json` and make changes: * Replace `"INSERT_OWNER_SLUG_HERE"` with your Kaggle username (e.g., `"YOUR_USERNAME"`). * Replace `"INSERT_EXISTING_MODEL_SLUG_HERE"` with your parent model's slug (e.g., `"my-awesome-ai-model"`). * Replace `"INSERT_INSTANCE_SLUG_HERE"` with a slug for this variation (e.g., `"jax-implementation"`). * Replace `"INSERT_FRAMEWORK_HERE"` with the model framework (e.g., `"jax"`, `"tensorflow"`, `"pytorch"`, `"sklearn"`). * Update the `"instance_size_bytes"` if known, and add a `"description"`. 5. **Create the model variation.** This uploads the files in the current directory (e.g., `flax_model.params`) along with the variation metadata. ```bash kaggle models variations create -p . ``` 6. **Verify on Kaggle.com.** Go to your model's page on Kaggle by clicking on the model under in the [`Models` tab on `Your Work`](https://www.kaggle.com/work/models). You should see a new "jax-implementation" variation listed, and it will have one version containing `flax_model.params`. ## Tutorial: Create a Model Variation Version This tutorial explains how to add a new version to an existing model variation, for example, when you have updated model weights or files. 1. **Ensure you have a model variation.** Follow the "Create a Model Variation" tutorial. Let's assume your variation is `YOUR_USERNAME/my-awesome-ai-model/jax/jax-implementation`. 2. **Prepare your updated files.** In your model variation directory (e.g., `my-new-model`), update or add new files for this version. For example, create `flax_model_v2.params`. ```bash # In the my-new-model directory echo "Updated JAX model parameters for V2" > flax_model_v2.params # You might also remove or update flax_model.params if it's being replaced ``` 3. **Create the new model variation version.** You need to specify the parent model variation and provide version notes. The files from the `-p` path will form the contents of this new version. ```bash # Replace YOUR_USERNAME and the slugs for model and variation accordingly kaggle models variations versions create YOUR_USERNAME/my-awesome-ai-model/jax/jax-implementation -p . -n "Second version with updated parameters" ``` *Note: The `-p .` means all files in the current directory will be uploaded as part of this new version. If you only want to upload `flax_model_v2.params`, ensure only it (and any other V2 files) are in a directory and point `-p` to that directory, or manage your files carefully.* 4. **Verify on Kaggle.com.** Go to your model variation page on Kaggle (e.g., `YOUR_USERNAME/my-awesome-ai-model/jax/jax-implementation`) by clicking on the [`Models` tab on `Your Work`](https://www.kaggle.com/work/models). You should see a new version (e.g., version 2) listed with your notes and the new files. ## Tutorial: How to Submit to a Competition This tutorial walks you through the process of making a submission to a Kaggle competition using the CLI. 1. **Find a Competition and Accept Rules.** * First, you need to find a competition. You can list active competitions using `kaggle competitions list`. * For this tutorial, we'll use the "titanic" competition, which is a common starting point. You can find it at [`https://www.kaggle.com/c/titanic`](https://www.kaggle.com/c/titanic). * **Important**: Before you can download data or submit, you *must* join the competition and accept the competition's rules on the Kaggle website. Navigate to the competition on kaggle.com to do this. 2. **Create a Directory and Download Competition Files.** * Create a new directory for your competition files and navigate into it. ```bash mkdir titanic-competition cd titanic-competition ``` * Download the competition files. This usually includes training data, test data, and a sample submission file. ```bash kaggle competitions download -c titanic ``` * This will download `titanic.zip`. You'll need to unzip it to see the files (e.g., `train.csv`, `test.csv`, `gender_submission.csv`). ```bash # Make sure you have unzip installed, or use your OS's GUI to extract # The actual zip file name might vary based on the competition. unzip titanic.zip ``` 3. **Create Your Submission File.** * The required format for the submission file is specific to each competition. You can find this information on the competition's "Evaluation" page or by examining the sample submission file (e.g., `gender_submission.csv` for the Titanic competition). * For the Titanic competition, the submission file needs two columns: `PassengerId` and `Survived`. The `Survived` column should contain your predictions (0 for deceased, 1 for survived). * Let's create a very simple submission file based on the `gender_submission.csv` (which predicts survival based on gender). For this tutorial, we'll just copy it and use it as our submission. In a real scenario, you would generate this file from your model's predictions on the `test.csv` data. ```bash cp gender_submission.csv my_submission.csv ``` * Your `my_submission.csv` should look something like this: ``` PassengerId,Survived 892,0 893,1 894,0 ... ``` 4. **Submit to the Competition.** * Use the `kaggle competitions submit` command. You need to specify: * The competition ID (`titanic`). * The path to your submission file (`-f my_submission.csv`). * A message describing your submission (`-m "My first submission via CLI"`). ```bash kaggle competitions submit titanic -f my_submission.csv -m "My first submission via CLI" ``` 5. **Check Your Submission Status.** * After submitting, you'll get a message indicating success or failure. * You can check your submission's score and status on the "My Submissions" tab of the competition page on Kaggle.com (e.g., [`https://www.kaggle.com/c/titanic/submissions`](https://www.kaggle.com/c/titanic/submissions)). * You can also list your recent submissions and their scores via the CLI: ```bash kaggle competitions submissions -c titanic ``` * This command will show your submission, its status (e.g., `complete`, `error`), and your public/private scores if available. ## Tutorial: How to Submit to a Code Competition This tutorial walks you through the process of submitting to a code competition on Kaggle. 1. **Find a Code Competition.** * First, you need to find a code competition to participate in. You can browse the available competitions on the [Kaggle competitions page](https://www.kaggle.com/competitions). Many Featured Competitions are code competitions. 2. **Download the Dataset.** * Once you have chosen a competition, you need to download the dataset. You can do this using the `kaggle competitions download` command: ```bash kaggle competitions download -c <competition-name> ``` * Replace `<competition-name>` with the name of the competition you want to participate in. 3. **Create a Notebook.** * Next, you need to create a Kaggle Notebook to work on your submission. A Kaggle Notebook contains the code and environment settings for Kaggle to run and evaluate your submission. Follow the tutorial on [Creating / Updating Notebooks](#tutorial-update-a-kernel-notebook) if you're not sure how to do this. 4. **Write Your Code.** * Now it's time to write your code! You can use any programming language or framework that is supported by Kaggle. The goal is to create a model that can make predictions on the test set. 5. **Submit Your Prediction.** * Once you are happy with your model, you can submit your prediction to the competition. You can do this using the `kaggle competitions submit` command: ```bash kaggle competitions submit <competition-name> -k <username>/<notebook-slug> -f <output-filename> -v <notebook-version> -m <message> ``` * Replace: * `<competition-name>` with the name of the competition * `<username>/<notebook-slug>` with the identifier of your notebook * `<output-filename>` with the name of the submission file produced by your notebook (e.g. `submission.csv`). * `<notebook-version>` with the version to submit (e.g. `3` to submit the 3rd version of your notebook). * `<message>` with a brief description of your submission. 6. **Check Your Score.** * After you have submitted your prediction, you can check your score on the competition leaderboard. The leaderboard shows the scores of all the participants in the competition. You can download the leaderboard using the `kaggle competitions leaderboard` command: ```bash kaggle competitions leaderboard <competition-name> ``` --- ### CHANGELOG Changelog ==== ### Next * Add `kaggle competitions host-add <comp> -u <user>` to grant host access on a competition to a Kaggle user * Suggest a next step on 403/404/429/5xx API errors, report unexpected errors as bugs instead of a traceback (with a new `--debug` flag), and list common examples in `kaggle --help` * Add `kaggle benchmarks quota` to show Model Proxy (AI inference) spend quota, and bump `kagglesdk` to `>= 0.1.37` * Add `kaggle competitions submission-download <id>` to download the submitted file for a single submission (requires `kagglesdk >= 0.1.36`) * Add `deadline` (Competition Deadline) to the competition settings command and bump `kagglesdk` to `>= 0.1.36` * Document that `NvidiaTeslaP100` is unusable for GPU compute with the default Kaggle image (PyTorch cu128 omits Pascal `sm_60` kernels) * 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 * fix(benchmarks): support owner/task separator in benchmark commands (#1146) * Feat/competition submissions limits (#1144) * add competitions solution create/status commands (#1141) * fix(cli): prevent stale file corruption when resuming downloads (#1142) * fix(cli): fix collaborator role handling in dataset metadata update (#1138) * Refactor paging to use Protocols (#1137) * fix(cli): retry transient connection errors in with_retry (#1132) * Add Kaggle Secrets documentation (#1131) * Fix model and owner slug validation (#1134) * Implement ignore_patterns in uploading (combined) (#1130) * Refactor parser fixtures (#1118) * fix(auth): avoid skipping auth for programmatic imports (#1117) * fix(cli): resumable upload start offset when zero bytes uploaded (#1113) * refactor(cli): reuse _resolve_projection in dataset_status (#1116) * update supported model list (#1115) * fix(cli): handle deleted comments in topics show (#1114) * Add leaderboard subcommand to kaggle benchmarks (#1112) * feat(cli): add competitions settings update command (#1104) * feat(cli): add competitions hosts list command (#1107) * feat(cli): add competitions settings get command (#1103) * feat(cli): support --page-token and --page-size, preserve --page (#1098) * feat(cli): expose userRank in competitions list output (#1094) * fix(cli): read kernel metadata and source files using UTF-8 in kernels_push (#1093) * Fix crash when running kaggle command with invalid credentials (#1092) * feat(cli): add competitions data push command (#1085) * fix(cli): restore fallback for unknown kernel language/type in kernels_pull (#1091) * fix(auth): prioritize OAuth credentials over anonymous fallback (#1089) * feat(cli): add competitions pages update command (#1083) * fix(cli): stop treating subcommand -v as version flag (#1082) * fix(cli): honor --unzip for cached dataset downloads (#1086) * feat(cli): add competitions pages delete command (#1084) * feat(cli): add competitions init and create commands (#1080) * docs(competitions): add competition_creation.md for new host commands (#1081) * feat(cli): add competitions launch command (#1079) * feat(cli): add competitions pages create command (#1078) * fix(cli): avoid success message after canceled model deletion (#1077) * fix(cli): avoid success message after canceled dataset deletion (#1073) ### 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) * Add `kaggle quota` command for GPU/TPU accelerator quota (#1029) * Support optional kernel version in specifier (#1035) * feat(benchmarks): Add log and download source files (#1019) * Fix benchmarks CLI error handling and UX improvements (#1024, #1026, #1028, #1030, #1032, #1037, #1039) * Fix JSON serialization and download label display (#1038, #1040, #1042) * Set proper permissions on auth file (#1033) ### 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) ### 2.1.2 * Update kagglesdk version ### 2.1.1 * Add instructions re kagglesdk (#1000) * fix(benchmarks cli): bugs and additional features (#997) * Add submission ref to competition submissions output (#989) * Add Gemini Agent Skill for Benchmarks CLI (#994) * (Off Platform SDK) add new models (#991) * fix (cli): kaggle benchmark tasks (#988) * Update `kaggle b init` to include example and reference (#990) * Update API token page URL (#987) * Update `b auth` and `b init` confirmations (#986) * Enable & document OAuth authentication flow. (#983) * Add `--format` flag to `datasets status` for JSON output (#972) ### 2.1.0 * Add `kaggle benchmarks init` command (#981) * Fix mypy typing checks (#979) * feat: Implement kaggle benchmark client (#955) * Update default Python version in cicd CB config * Make a list (#978) ### 2.0.2 * Add `kaggle benchmarks auth` command (#976) * Create Cloud Build script to run linter (#974) * Add `kaggle kernels logs` CLI command (#966) * Fix(benchmarks tasks push): handle 403 (#971) * Fix: respect Retry-After header on HTTP 429 responses (#938) (#940) * Update kagglesdk dependency version to 0.1.19 (#970) * Support `dataset-cover-image.png` upload for `datasets metadata --update` (#969) * Add CLI commands for simulation episodes and competition pages (#968) * Feature(benchmarks): implement Kaggle client (push/run functionality) (#960) ### 2.0.1 * Add `--sandbox` flag to `kaggle competitions submit` for sandbox submissions (competition hosts/admins only) (#932) * Optimize large dataset download functionality (#936, s/o katoue) * Fix 403s and null file handling when listing kernel session output (#951, s/o 4kaws) * Support updating more types of dataset metadata through `datasets metadata --update`: * Expected update frequency, user specified sources (#958) * Dataset images (#959) ### 2.0.0 * General Availability release * Change more "instance" to "variation" * Update link for the integration test auth instructions (#926) * Fix string formatting in upgrade nudge message (#928) Thanks PythonicVarun! ### 1.8.4 * Rename `kaggle-api` to `kaggle-cli` * Allow auth to happen multiple times (#922) * Add --acc to set accelerator for: kaggle kernels push ... (#907) * Add automatic retry and resume to download_file (#905) Thanks katoue! * Restore model validation check (#902) * Add file pattern matching in output download (#901) Thanks piotr-ginal! ### 1.8.3 * Add packaging dep (#883) * Add version checking against server known-version (#880) * Fix edit error (#876) * Use kagglesdk from pypi (#875) * Fix Kaggle access token auth KeyError when KAGGLE_API_TOKEN is unset (#874) ### 1.8.2 * Changes to build script ### 1.8.1 * Fix memory exhaustion when downloading large files (#869) * Add python-dateutil to pyproject.toml dependencies (#866) ### 1.8.0 * Fix resumable download error (#865) * Fix dataset version spec (#862) * Add machine_shape to the metadata of kaggle kernels pull (#856) * Add pagination options to models * Add pagination options for submissions (#832) * Add pagination options to list commands (#815) * Add canonical aliases for push/pull (#787) * Add parquet as a filter option (#786) * Add variations as alt for instances (#784) * Enable (and rename) synonyms i and v (#782) ### 1.7.5.0 (not released) * Require Python 3.11. * Add KernelExecutionType (#775) * Output docker_image as part of the pull metadata (#773) * Allow user to specify docker_image during kernel push (#774) * Add kernel version type to save request (#771) * Add tests for delete and de-flake (#769) * Rename "yes" params and make confirmation consistent (#765) * Fix bug that caused double serialization (#764) * Add kaggle kernels delete (#762) * Add test for dataset_delete() and make script more robust (#760) * Check dataset status before uploading (#759) * Add kaggle datasets delete (#755) * Fix calls to download_file() (#752) * Add type annotations for mypy (#746) * Use Optional[...] in cases where the proto file does (#744) * Improve some type hints and fix a bug (#741) * Reformat everything with black (#737) * Add more type hints (#736) * Add type annotations to main file (#735) * Bulk reformat docstrings (#732) * Merge envars before sending a request (#729) * Use PROD if no environment is specified. (#726) * Add a no response action to auto-close issues (#723) ### 1.7.4.2 * Fix a problem in downloading kernel output files. ### 1.7.4.1 * Fix a dataset download problem. Datasets that had a license were failing to download. * Update the documentation to include code competition submit. ### 1.7.4 Version 1.7.3 was never released. There were errors in versioning on test.pypi.org. For consistency, we decided to jump several version numbers. This is the first release since 1.6.17. The actual changes are described in 1.7.3. ### 1.7.3 There was an error in versioning. We went from 1.6.17 to 1.7.3. * Added the ability to submit to a code competition. Some required arguments have been made optional. * Added a `--timeout` option to `kaggle kernels push` to limit the run-time to the specified number of seconds. * Removed Swagger. Projects that use `kaggle/api/kaggle_api.py` may be affected. That file is deprecated and will be removed. Most of its functions still work, but those that involve uploading files no longer work. The command-line tool uses a higher-level abstraction for uploading, and client code needs to be converted to use that. ### 1.7.3b2 * Added the ability to submit to a code competition. Some required arguments have been made optional. * Added a `--timeout` option to `kaggle kernels push` to limit the run-time to the specified number of seconds. ### 1.7.3b1 * Fix escaped-quote issue in HTTP requests. ### 1.7.3b0 * Remove Swagger. No user-visible changes to the command-line tool. However, projects that use `kaggle/api/kaggle_api.py` may be affected. That file is deprecated and will be removed. Most of its functions still work, but those that involve uploading files no longer work. The command-line tool uses a higher-level abstraction for uploading and client code needs to be converted to use that. ### 1.6.17 * No changes; release 1.6.16 did not complete. ### 1.6.16 * No changes; release 1.6.15 isn't usable. We're working on process updates to prevent this from happening again. ### 1.6.15 * Support XDG base directory specification on Linux * Disable out-of-date API version warning with -W * Allow an array of strings in "source" when uploading .ipynb files (thanks to GitHub user mgallifrey for the contribution!) * Add triton framework for models * Update model licenses ### 1.6.14 * No changes; release 1.6.13 isn't usable. ### 1.6.13 * Add --page-size and --page-token CLI options to all commands that display lists of files. ### 1.6.12 * Re-release 1.6.11 without the `src` directory included in the package. ### 1.6.11 * Allow unauthenticated usage of "datasets download", "datasets files". * This will only work after April 8th, 2024. More more details, see: <https://www.kaggle.com/discussions/product-feedback/485439> * Allow "help" and "version" to be used for all commands, unauthenticated. * Fix: "dataset download -f" can accept a specific dataset version. ### 1.6.10 Repackage of 1.6.8 as a new release, to fix the problematic 1.6.9 release. ### 1.6.9 * Do not use. Problematic release that causes an error: `ModuleNotFoundError: No module named 'kaggle.api'` ### 1.6.8 * Add "gguf" ### 1.6.7 * Add "TensorRtLlm" model framework. ### 1.6.6 * Add "GemmaCpp" and "GGML" model frameworks. ### 1.6.5 * Add "MaxText" model framework. ### 1.6.4 * Add "Transformers" model framework. ### 1.6.3 Release date: 01/11/24 * Add "Flax" and "Pax" model frameworks. ### 1.6.2 Release date: 01/09/24 * Add "Other" model framework. ### 1.6.1 Release date: 01/08/24 * Fix dataset/model upload. ### 1.6.0 Release date: 01/04/24 * Release the pre-release branch with models endpoints. #### 1.6.0a7 Release date: 11/22/23 * Add model_instance_type and base_model_instance_id to ModelInstance #### 1.6.0a6 Release date: 9/19/23 * Include version_number and version_id in the model-instance-metadata.json file #### 1.6.0a5 Release date: 8/02/23 * Add Keras model framework. #### 1.5.16 Release date: 7/17/23 * Fix dataset download bug with locale * Resumable uploads * Retry some failed requests #### 1.6.0a4 Release date: 7/07/23 * Resumable uploads * Retry some failed requests * Flag `-y` to delete model/instance/version without confirmation #### 1.6.0a3 Release date: 7/06/23 * Confirmation for deleting a model, instance or version * Merge changes from 1.5.14 and 1.5.15 #### 1.5.15 Release date: 6/30/23 * Add missing licenses for datasets * Re-add option to pass dataset with `-d` * Download / list files for a specific version of a dataset * Documentation improvements #### 1.5.14 Release date: 6/29/23 * Show the full error message from the API * Improve and fix documentation * Fix kernel's data sources bug, and add the model data source to push/pull * Implement resumable downloads * Fix unreachable code bug * Make some arguments required * Add enable_tpu to kernel's push/pull #### 1.6.0a2 Release date: 6/12/23 * Add endpoint to get a modelInstance * Simplify the modelInstanceVersion creation * Fix Model files zipping #### 1.6.0a0 Release date: 6/07/23 * Add Models endpoints #### 1.5.13 Release date: 2/27/23 * Add ability to add a model to a kernel ### 1.5.12 Release date: 03/12/21 * No changes ### 1.5.11 Release date: 03/12/21 * Add support for non-ASCII characters for kernels. ### 1.5.10 Release date: 11/30/20 * Remove dependency on slugify. ### 1.5.9 Release date: 10/21/20 * Drop version restriction on urllib3 in setup.py. ### 1.5.8 Release date: 09/03/20 * No user-facing changes #### 1.5.7 Release date: 8/31/20 * Add ability to specify the kernel docker image pinning type * Kernels have internet enabled by default * Various competitions fixes #### 1.5.6 Release date: 9/19/19 * Downloading all files for a competition downloads a zip instead of individual files #### 1.5.5 Release date: 8/30/19 * Add vote count and usability rating to datasets listing * Add min and max dataset size filters to datasets listing * Add additional information to dataset metadata API * Allow updating dataset metdata #### 1.5.4 Release date: 5/28/19 * Make kernels init more friendly * Make directories if needed for kernels output #### 1.5.3 Release date: 2/20/19 * Bump urllib3 version #### 1.5.2 Release date: 1/28/19 * Don't error on encoding errors when printing tables * Exit with error code when an exception is caught #### 1.5.1.1 Release date: 12/5/18 * Add missing cli option for dataset subfolders #### 1.5.1 Release date: 12/5/18 * Allow custom ca_cert files * Support uplodaing datasets with subfolders * Fix kaggle.json permissions warning #### 1.5.0 Release date: 10/19/18 * Update API to work with new competitions submissions backend. This change will force old API clients to update. * Update error message when config file is not found. #### 1.4.7.1 Release date: 8/28/18 * Fix host #### 1.4.7 Release date: 8/28/18 * Make dataset version `-p` argument actually optinal * Don't require the `resources` field when updating a dataset * Don't automatically unzip datasets * Add an unzip option for dataset downloads * Add validation for kernel title and slug length * Give a warning if kernel title does not resolve to the specified slug * Show kernel version number after pushing * Respect `code_file` value in kernel metadata when pulling kernels #### 1.4.6 Release date: 8/7/18 * Allow setting config values through environmental variables #### 1.4.5 Release date: 8/1/18 * Add error if dataset metadata repeats files #### 1.4.4 Release date: 7/30/18 * Fix issue with reading kernel metadata #### 1.4.3 Release date: 7/30/18 * Add more competitions list options * Add more datasets list options * Add a couple more fields to kernels list display * Add support for kernel and dataset ID's * Allow generating metadata for an existing dataset * Fix issue with downloading from datasets whose titles don't match their slugs * Use kernel slug as filename for kernel output * Make upload and download directory default to current working directory * Use a default username on downloading kernel or dataset data if none is specified * Support extended data types on datasets * Stop requiring `-c`, `-d`, and `-k` arguments * Don't require `resources` field in dataset metadata #### 1.4.2 Release date: 7/20/18 * Validate dataset slug and title length before uploading * Fix issue with dataset metadata file detection * Cleaned up KeyboardInterrupt errors * Validate all specified files in a dataset exist prior to uploading * Make ApiExceptions (slightly) less ugly #### 1.4.1 Release date: 7/20/18 * Add python 3.7 compatibility #### 1.4.0 Release date: 7/19/18 * Add kernels support ** List and search kernels ** Push kernels code ** Pull kernels code ** Download kernel output ** Get latest kernel run status #### 1.3.12 Release date: 6/25/18 * Allow setting a `'KAGGLE_CONFIG_DIR'` environmental token * Return metadata file after creating * Alert users that dataset creation takes time #### 1.3.11.1 * Fix other invalid tags check #### 1.3.11 Release date: 6/12/18 * Improve version check * Fix invalid tags check #### 1.3.10 Release date: 6/10/18 * Restrict urllib3's version due to requests dependency problem #### 1.3.9.1 Release date: 6/9/18 * Fix bug with competitions submissions. #### 1.3.9 Release date: 6/8/18 * Improve error message for closed competitions * Remove stacktrace on errors * Print any invalid tags * Warn if there are no competition files to download * Implement resumable uploads * Add subtitle metadata to dataset uploads * Add progress bars for uploads and downloads * Add command for downloading competitions leaderboard * Add command for viewing the top of the leaderboard #### 1.3.8 Release date: 5/18/18 * Add option to delete all previous dataset versions #### 1.3.7 Release date: 5/18/18 * Add aliases for subcommands (ex. `kaggle c` is the same thing as `kaggle competitions`) * Add version command * Show full download path for files * Remove file size limitation from uploads #### 1.3.6 Release date: 5/7/18 * Give the option to add tags to datasets. * Known limitiation - you cannot delete tags through the API. Those changes must be done through the website. #### 1.3.5 Release date: 5/4/18 * Fix schema declaration in dataset resources #### 1.3.4 Release date: 4/30/18 * Rename `columns` to `fields` #### 1.3.3 Release date: 4/26/18 * Fix UnicodeEncodeError for certain datasets * Include Swagger yaml and config files #### 1.3.2.1 Release date: 4/24/18 * Fix bug with column metadata #### 1.3.2 Release date: 4/24/18 * Give the option to specify a schema for uploaded datasets * Give the option to set the dataset description during updates #### 1.3.1 Release date: 4/19/18 * Give the option to set dataset file descriptions * Give the option to not convert tabular datasets to csv #### 1.3.0 Release date: 4/18/18 * Give the option to set the dataset description during creation #### 1.2.1 Release date: 4/17/18 * [Issue #5](https://github.com/Kaggle/kaggle-api/issues/5) - Reformat code for consistency and to align with [Google's python coding style](https://google.github.io/styleguide/pyguide.html). Most of the changes are cosmetic, but most cases of `camelCasing` other than class names have been changed to `snake_case`. This is a breaking change for anyone directly using the python code rather than simply using the command line. --- ### CONTRIBUTING # How to Contribute We'd love to accept your patches and contributions to this project. There are just a few small guidelines you need to follow. ## Contributor License Agreement Contributions to this project must be accompanied by a Contributor License Agreement. You (or your employer) retain the copyright to your contribution; this simply gives us permission to use and redistribute your contributions as part of the project. Head over to <https://cla.developers.google.com/> to see your current agreements on file or to sign a new one. You generally only need to submit a CLA once, so if you've already submitted one (even if it was for a different project), you probably don't need to do it again. ## Code reviews All submissions, including submissions by project members, require review. We use GitHub pull requests for this purpose. Consult [GitHub Help](https://help.github.com/articles/about-pull-requests/) for more information on using pull requests. ## Community Guidelines This project follows [Google's Open Source Community Guidelines](https://opensource.google.com/conduct/). --- ### README # Kaggle CLI The official CLI to interact with [Kaggle](https://www.kaggle.com). --- [User documentation](docs/README.md) --- ## Key Features Some of the key features are: * List competitions, download competition data, submit to a competition. * List, create, update, download or delete datasets. * List, create, update, download or delete models & model variations. * List, update & run, download code & output or delete kernels (notebooks). * Browse and read discussion forums. ## Installation Install the `kaggle` package with [pip](https://pypi.org/project/pip/): ```sh pip install kaggle ``` Additional installation instructions can be found [here](docs/README.md#installation). ## Quick start Explore the available commands by running: ```sh kaggle --help ``` See the [User documentation](docs/README.md) for more examples & tutorials. ## Hosting a competition End-to-end host commands — scaffold a new competition, author its pages, tune its settings, and launch it — are documented in [docs/competition_creation.md](docs/competition_creation.md). Covers `kaggle competitions init`, `create`, `pages create`, `hosts`, `settings get`, `settings update`, and `launch`. ## Development ### `kagglesdk` Updates New features that interact with `kaggle.com` probably require changes to the Python library, `kagglesdk`. Make sure to bump the minimum version required for `kagglesdk` in the `dependencies` list specified in [pyproject.toml][pyproject.toml]]. Make sure the required version is available on the [pypi.org kagglesdk project](https://pypi.org/project/kagglesdk/#history). ### Prerequisites We use [hatch](https://hatch.pypa.io) to manage this project. Follow these [instructions](https://hatch.pypa.io/latest/install/) to install it. ### Run `kaggle` from source #### Option 1: Execute a one-liner of code from the command line ```sh hatch run kaggle datasets list ``` #### Option 2: Run many commands in a shell ```sh hatch shell # Inside the shell, you can run many commands kaggle datasets list kaggle competitions list ... ``` ### Lint / Format ```sh # Lint check hatch run lint:style hatch run lint:typing hatch run lint:all # for both # Format hatch run lint:fmt ``` ### Tests Note: These tests are not true unit tests and are calling the Kaggle web server. ```sh # Run against kaggle.com hatch run test:prod # Run against a local web server (Kaggle engineers only) hatch run test:local ``` ### Integration Tests To run integration tests on your local machine, you need to set up your Kaggle credentials. You can do this by following the [authentication instructions](docs/README.md#authentication). After setting up your credentials, you can run the integration tests as follows: ```sh hatch run test:integration ``` ### Code Coverage We measure code coverage using `pytest-cov`. To run unit tests with coverage and generate reports: ```sh hatch run test:cov ``` This generates: * Terminal output with a coverage summary. * `coverage.xml` (XML report in the root, used by IDE integrations). * `htmlcov/index.html` (HTML report for browser viewing). #### Editor Integration ##### VSCode Install the **Coverage Gutters** extension. After running the coverage command, click the **Watch** button in the status bar to see coverage indicators in the editor margins. ##### JetBrains Rider With the **Python** plugin installed: * **Run with Coverage:** Create a Pytest run configuration and click the shield icon ("Run with Coverage"). * **Import Report:** Go to **Tools** -> **Show Code Coverage Data**, click **Add** (+), and select `coverage.xml`. ### Running `hatch` commands inside Docker This is useful to run in a consistent environment and easily switch between Python versions. The following shows how to run `hatch run lint:all` but this also works for any other hatch commands: ``` # Use default Python version ./docker-hatch run lint:all ``` ## Changelog See [CHANGELOG](CHANGELOG.md). ## Contributing See [CONTRIBUTING.md](CONTRIBUTING.md). ## License The Kaggle CLI is released under the [Apache 2.0 license](LICENSE.txt). --- ### SECURITY # Security Policy ## Supported Versions Security updates are applied only to the latest release. ## Reporting a Vulnerability If you have discovered a security vulnerability in this project, please report it privately. **Do not disclose it as a public issue.** This gives us time to work with you to fix the issue before public exposure, reducing the chance that the exploit will be used before a patch is released. Please disclose it at [security advisory](https://github.com/Kaggle/kaggle-cli/security/advisories/new). The vulnerabilities will be addressed as soon as possible, with a maximum of 90 days before a public exposure. ---