DOCSEARCHbyAlgolia
Submit Docs

Kaggle CLI

repository·main·Indexed 27 days ago

https://github.com/kaggle/kaggle-cli

The official command-line interface for interacting with Kaggle. It enables users to manage competitions, datasets, models, kernels, and benchmarks, as well as browse discussion forums. The CLI supports multiple authentication methods including OAuth, environment variables, and API token files.

Tokens
32.1K
Snippets
73
Records
237
Agent score
91%

What's inside kaggle-cli

  1. Manage framework-specific model variations with `kaggle models variations`

    main

    Use the kaggle models variations command (or its legacy aliases kaggle models instances, kaggle models v, and kaggle models i) to manage framework-specific variations of a Kaggle Model.

    Prerequisites:

    • Python 3.11+ with the kaggle package installed.
    • Kaggle credentials for private models and mutation commands.
    • An existing model for create flows.
    • For init, create, or update flows, you must use a model-instance-metadata.json file.

    Variation Handle Format: <owner>/<model-name>/<framework>/<variation-slug>

  2. Create or retrieve kernel-metadata.json files

    main

    To upload and run a Kaggle kernel, you must provide a kernel-metadata.json file.

    • To generate a new metadata file: Use the kaggle kernels init command with the -p flag to specify the directory where the file should be created.
    • To retrieve metadata from an existing kernel: Use the kaggle kernels pull command with the -k flag (specifying username/kernel-slug), the -p flag (for the download path), and the -m flag to specifically pull the metadata.

  3. Run Kaggle CLI from source using Hatch

    main

    This project uses hatch for environment and dependency management. You can run the CLI directly from the source code using one of two methods:

    Option 1: Execute a single command

    hatch run kaggle datasets list

    Option 2: Enter a managed shell

    hatch shell
# Once inside the shell, you can run commands directly
kaggle datasets list
kaggle competitions list

  4. Initialize Model Variation metadata

    main

    A model variation represents a specific version of a model (e.g., B0, B1) with a specific framework (e.g., TensorFlow2). To create a variation, you must provide a model-instance-metadata.json file. You can generate a template for this file using the kaggle models variations init command.

    Metadata Fields for model-instance-metadata.json:

    • 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 framework (e.g., tensorFlow1, tensorFlow2, tfLite, tfJs, pyTorch, jax, coral).
    • overview: A short overview of the variation.
    • usage: Usage instructions in Markdown.
    • fineTunable: Boolean indicating if the variation is fine-tunable.
    • trainingData: A list of strings, URLs, or Kaggle Datasets used for training.
    • modelInstanceType: Type of variation (base model, external variant, internal variant, or Unspecified).
    • baseModelInstance: If an internal variant, the {owner-slug}/{model-slug}/{framework}/{variation-slug} of the base model.
    • externalBaseModelUrl: If an external variant, the URL to the base model.

  5. Write a Kaggle Benchmark Task file

    main

    Benchmark tasks are Python scripts using the kaggle-benchmarks library. They must follow these rules:

    1. Import: Use import kaggle_benchmarks as kbench.
    2. Decorate: Define at least one function with the @kbench.task(...) decorator.
    3. Execute: You must call .run(kbench.llm) (or .evaluate()) on the task function. Without this call, no .run.json output is produced, and the task will silently produce no results on the server.
    4. Format: Use "percent format" with # %% cell markers to separate notebook cells. The CLI uses jupytext to convert these to .ipynb files.
    5. Naming: If name= is omitted in @kbench.task(), the name defaults to the function name (title-cased, underscores replaced by spaces) and is then slugified (e.g., my_eval becomes my-eval).

    Warning: The slug used in the CLI must match the slugified version of the @task decorator name.

    # %%
import kaggle_benchmarks as kbench

# %%
@kbench.task(name="sample-task")
def sample_task(llm):
    response = llm.prompt("What is 2 + 2?")
    kbench.assertions.assert_in("4", response, expectation="Should contain 4")

sample_task.run(kbench.llm)

  6. Prerequisites for Kaggle Models CLI

    main

    To use the kaggle models (or kaggle m) commands, ensure you meet the following requirements:

    • Python Environment: Python 3.11+ with the kaggle package installed.
    • Authentication: Kaggle credentials must be configured for operations involving private model access or create/update/delete actions.
    • Metadata Preparation: For create or update workflows, you must have a model-metadata.json file. You can generate a starter file using kaggle models init -p <FOLDER>.

  7. Manage simulation competition episodes and replays

    main

    For simulation competitions, use the following commands to debug and review agent performance:

    • List episodes: kaggle competitions episodes <SUBMISSION_ID> lists episodes associated with a submission.
    • Download replay: kaggle competitions replay <EPISODE_ID> -p <PATH> downloads the replay artifact for a specific episode.
    • Download logs: kaggle competitions logs <EPISODE_ID> <AGENT_INDEX> -p <PATH> downloads per-agent logs (where <AGENT_INDEX> is a zero-based position).

  8. Host a Kaggle competition

    main

    The CLI provides end-to-end commands for hosting competitions, including scaffolding, page authoring, settings management, and launching. Key commands include:

    • kaggle competitions init
    • create
    • pages create
    • hosts
    • settings get
    • settings update
    • launch

    Detailed documentation for these workflows is available in docs/competition_creation.md.

  9. Download competition data and accept rules

    main

    Before interacting with simulation competitions via the CLI, you must manually accept the competition rules on the Kaggle website (e.g., by clicking "Join Competition").

    Once rules are accepted, you can download the competition's starter kit and data using the download command. Use the -p flag to specify a destination directory.

  11. Refresh Model Proxy credentials with `kaggle benchmarks auth`

    main

    Use kaggle benchmarks auth to refresh only the Model Proxy credential variables (MODEL_PROXY_URL, MODEL_PROXY_API_KEY, and MODEL_PROXY_EXPIRY_TIME) without generating new starter task files.

    Options:

    • -y, --yes: Skip confirmation prompts.
    • --env-file <FILE>: Path to append the credential variables to.