JosiahSiegel/notebook-lifecycle

Notebook Lifecycle

Overview

Use this skill for local-to-Kaggle notebook administration: initialize, push, pull, run, inspect status/logs/files, download outputs, and delete kernels. Treat Kaggle Notebooks and Kaggle kernels as the same operational surface for CLI/API purposes.

Quick Reference

| Task | Kaggle CLI | |---|---| | List kernels | kaggle kernels list | | Initialize folder | kaggle kernels init -p <folder> | | Push/update/run | kaggle kernels push -p <folder> [-t <timeout>] [--accelerator <ID>] | | Pull source + metadata | kaggle kernels pull <owner/slug> -p <folder> -m | | Status | kaggle kernels status <owner/slug> | | Files | kaggle kernels files <owner/slug> | | Outputs | kaggle kernels output <owner/slug> -p <folder> -o [--file-pattern <REGEX>] | | Logs | kaggle kernels logs <owner/slug> | | Delete | kaggle kernels delete <owner/slug> --yes |

Authentication

Verify authentication before lifecycle commands. Supported public mechanisms include kaggle auth login, KAGGLE_API_TOKEN, ~/.kaggle/kaggle.json, and ~/.kaggle/access_token. Do not print token contents in responses or logs. When troubleshooting auth, check file presence and permissions without exposing secrets.

Standard Workflow

1. Initialize or inspect the local folder.
2. Validate kernel-metadata.json before push; load kernel-metadata for schema repair.
3. Confirm source file referenced by code_file exists and matches kernel_type/language.
4. Choose a conservative timeout and accelerator. Warn before quota-consuming GPU/TPU runs.
5. Push with kaggle kernels push -p <folder> and optional -t or --accelerator.
6. Poll kaggle kernels status <owner/slug> until complete or failed.
7. Use logs, files, and output to diagnose or retrieve artifacts.

Pull and Synchronization

Use kaggle kernels pull <owner/slug> -p <folder> -m when the user needs both source and metadata. Treat pulls into non-empty folders as overwrite-sensitive: ask before replacing local work, or advise using a fresh folder. After pulling, compare metadata and code before pushing changes back.

Output Retrieval

Use kaggle kernels output <owner/slug> -p <folder> -o to download all outputs. Add --file-pattern <REGEX> to limit large output sets, for example submission files or model artifacts. Verify expected files exist before competition submission.

For long-running service or tunnel notebooks, do not rely only on logs for externally needed connection details. Logs may be blank during keepalive cells. Write discovered values such as a public tunnel URL to /kaggle/working/ollama_base_url.txt, then retrieve them with:

kaggle kernels output <owner>/<kernel-slug> -p ./outputs -o --file-pattern "ollama_base_url.txt"

Deriving a Notebook Browser URL After Push

After a successful kaggle kernels push, the Kaggle CLI does not provide a documented, stable contract that stdout includes a notebook URL. For e2e administration, derive the browser URL from kernel-metadata.json when its id field uses the documented identifier format owner/kernel-slug:

https://www.kaggle.com/code/<owner>/<kernel-slug>

Before the first successful push, call this the expected URL. After a successful push and status check, call it the notebook URL:

kaggle kernels push -p <notebook-folder>
kaggle kernels status <owner/kernel-slug>

Do not rely on parsing kaggle kernels push output for a URL; CLI text may change. Do not rely on undocumented CSV columns from list commands for URL construction. Private notebooks may require sign-in or appropriate permissions, and slug changes after renames can make older derived URLs stale.

Python API Equivalents

Use KaggleApi().authenticate() before API calls. Relevant methods include kernels_push, kernels_status, kernels_pull, kernels_output, kernels_list, kernels_logs, and kernels_delete. Prefer CLI examples for users unless they explicitly ask for Python automation.

Safety Gates

Require explicit confirmation before kaggle kernels delete <owner/slug> --yes; deletion is permanent. Also require confirmation before public visibility changes, overwriting local folders, pushing code that may contain secrets, or long accelerator-backed runs. If secrets appear in notebook source or metadata, stop and recommend moving them to Kaggle Secrets rather than pushing.

Public API Limitations

Do not claim public API support for notebook scheduling, secrets management, collaborator administration, cell-level editing of hosted notebooks, Docker image selection, or quota management. Suggest Kaggle UI workflows only when appropriate.

Sources

• Kaggle kernels CLI: https://github.com/Kaggle/kaggle-api/blob/main/docs/kernels.md
• Kaggle notebooks docs: https://www.kaggle.com/docs/notebooks
• Kaggle API docs: https://www.kaggle.com/docs/api