# 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).