Category: api
Question: How to use Kaggle's API / CLI for interacting with Notebooks?
Answer: The Kaggle API and CLI tool provide easy ways to interact with Notebooks on Kaggle. The commands available enable both searching for and downloading published Notebooks and their metadata as well as workflows for creating and running Notebooks using computational resources on Kaggle.

If you haven’t installed the Kaggle Python package needed to use the command line tool or generated an API token, check out the getting started steps first.

Some of the commands for interacting with Notebooks via CLI include:

- `kaggle kernels list -s [KEYWORD]`: list Notebooks matching a search term
- `kaggle kernels push -k [KERNEL] -p /path/to/folder`: create and run a Notebook on Kaggle
- `kaggle kernels pull [KERNEL] -p /path/to/download -m`: download code files and metadata associated with a Notebook

If you are creating a new Notebook or running a new version of an existing Notebook on Kaggle, you can also use the API to make this workflow convenient or even programmatic. View all available commands on the official documentation on GitHub [here](https://github.com/Kaggle/kaggle-api#kernels) and keep up-to-date with the latest features and bug fixes in the [changelog](https://github.com/Kaggle/kaggle-api/blob/master/CHANGELOG.md).

To explore additional CLI arguments, remember that you can always append `-h` after any call to see the help menu for that command.

# Creating and Running a New Notebook

The Kaggle API can be used to create new Notebooks and Notebook versions on Kaggle from the comfort of the command-line. This can make executing and sharing code on Kaggle a simple part of your workflow.

If you haven’t installed the Kaggle Python package needed to use the command line tool or generated an API token, check out the getting started steps first.

Here are the steps you can follow to create and run a new Notebook on Kaggle:

1. Create a local folder containing the code files you want to upload (e.g., your Python or R notebooks, scripts, or RMarkdown files)
2. Run `kaggle kernels init -p /path/to/folder` to generate a metadata file [here](https://github.com/Kaggle/kaggle-api/wiki/Kernel-Metadata)
3. Add your Notebook's metadata to the generated file, `kernel-metadata.json`; As you add your title and slug, please be aware that Notebook titles and slugs are linked to each other. A Notebook slug is always the title lowercased with dashes (-) replacing spaces and removing special characters.
4. Run `kaggle kernels push -p /path/to/folder` to create and run the Notebook on Kaggle

Your Notebook will be private by default unless you set it to public in the metadata file. You can also navigate to "Options" > “Sharing” from your published Notebook's page to make it public or share with collaborators.

# Creating and Running a New Notebook Version

If you’d like to create and run a new version of an existing Notebook, follow these steps:

1. Run `kaggle kernels pull [KERNEL] -p /path/to/download -m` to download your Notebook's most recent code and metadata [files](https://github.com/Kaggle/kaggle-api/wiki/Kernel-Metadata) (if your local copies aren't current)
2. Make sure the `id` field in `kernel-metadata.json` points to your Notebook; you no longer need to include the `title` field which is optional for Notebook versions unless you want to rename your Notebook (make sure to update the `id` field in your next push AFTER the rename is complete)
3. Run `kaggle kernels push -p /path/to/folder`

These instructions are the basic commands required to get started with creating, running, and updating Notebooks on Kaggle. You can find out more details from the official documentation on GitHub:

- Initializing metadata [here](https://github.com/Kaggle/kaggle-api#initialize-metadata-file-for-a-kernel)
- Push a Notebook [here](https://github.com/Kaggle/kaggle-api#push-a-kernel)
- Pull a Notebook [here](https://github.com/Kaggle/kaggle-api#pull-a-kernel)
- Retrieve a Notebook's output [here](https://github.com/Kaggle/kaggle-api#retrieve-a-kernels-output)