Kaggle CLI

Use kaggle for competition, dataset, kernel, and model operations from the shell. The official Kaggle skills document every command and metadata file; this skill owns authentication, download scope, and the authority boundary around submissions and publications.

Workflow

1. Resolve the account: kaggle auth login (OAuth) or KAGGLE_API_TOKEN in the environment; the legacy ~/.kaggle/kaggle.json still works. Never run kaggle auth print-access-token during ordinary work.
2. Read before writing: use bounded list/file commands and kaggle competitions submission-limits <slug> --json to inspect available data and submission limits. Read the competition's current rules separately with kaggle competitions pages list list <slug> --content --page-name rules (the repeated list is required by the CLI parser); these calls do not authorize accepting them.

3. Download into an ignored directory: accept the competition rules on the website first (the CLI returns 403 otherwise).

   kaggle competitions download <slug> -p data/ --unzip
   kaggle datasets download <owner>/<name> -p data/ --unzip

4. Track the timeline: after accepting rules, list the page names with kaggle competitions pages list list <slug>, then read the deadlines with --page-name timeline (or description when no timeline page exists). Offer, or schedule when requested, Google Calendar reminders with gws: one week before the entry and team merger deadline, and on the final submission day.
5. Inspect kernels before pushing: kaggle kernels init -p <dir> writes kernel-metadata.json. Before an authorized kaggle kernels push -p <dir>, inspect the upload directory, target ID, data sources, is_private, accelerator, internet access, and run timeout (--accelerator overrides the metadata's GPU/TPU settings, -t sets the run timeout): pushing uploads code and starts remote execution unless --no-run saves the version without running it. Keep is_private: true unless public release was explicitly requested, and inspect kaggle quota before accelerator use. Verify with kaggle kernels status <owner>/<slug> and retrieve artifacts with kaggle kernels output <owner>/<slug> -p out/.

6. Submit with authority: a submission counts against the daily limit and shows on the leaderboard, so confirm the competition, file, and message first. --wait <seconds> polls until scoring finishes and exits non-zero on a scoring error or timeout, though the submission still counts; otherwise look up the printed ref with kaggle competitions submission <ref>.

   kaggle competitions submit <slug> -f submission.csv -m "<message>" --wait 900
   kaggle competitions submissions <slug> --format json --page-size 5

7. Publish with authority: kaggle datasets create -p <dir> creates a private dataset unless --public is explicitly authorized. kaggle datasets version -p <dir> -m "<message>" updates an existing dataset and retains its visibility; it has no --public flag, and its -d/--delete-old-versions deletes the dataset's history, so pass it only when that deletion was requested. Verify the target dataset's current visibility before uploading a version, and confirm the license and intended audience before either operation.

Gotchas

• Use uv run for pinned versions: in a project that pins kaggle, call uv run kaggle so the pinned version runs instead of the global shim.
• Version warnings can reach stdout: -W applies only after import-time authentication, which can already print the out-of-date warning; keep kaggle current and drop leading Warning: lines before parsing JSON.

Official Skills

Upstream: Kaggle/kaggle-cli for command guidance and Kaggle/kaggle-skills for hackathon judging, agent exams, and Kaggle Benchmarks authoring. Follow the shared vendor-skill policy and install only the source relevant to the task.

Documentation

• Kaggle CLI · Kaggle API
• Releases: Kaggle CLI
• Companion skills: gws (calendar reminders), python-stack (project layout), duckdb (inspect downloads), hf (Hub models and datasets), colab (rented accelerators).