kgnite

kgnite is a practical command-line companion for Kaggle. It brings resource discovery, downloads, uploads, competition setup, notebook generation, submissions, and score tracking into one consistent CLI.

New to the browser interface? Read the kgnite Web Workstation Guide for page-by-page instructions and practical examples.

It uses:

the Kaggle CLI for search, metadata, file listings, notebook source, and competition actions;
kagglehub for downloads and handle-based dataset/model uploads;
local JSON files for competition workspace configuration and score history.

Requirements

Python 3.11 or newer
Kaggle CLI available as kaggle
internet access for Kaggle operations
valid Kaggle credentials

Confirm the prerequisites:

python3 --version
kaggle --version
kaggle config view

Authentication

The recommended method is a Kaggle API token:

export KAGGLE_API_TOKEN="your_token_here"

To persist it in Zsh:

echo 'export KAGGLE_API_TOKEN="your_token_here"' >> ~/.zshrc
source ~/.zshrc

The following legacy methods are also supported:

~/.kaggle/kaggle.json
KAGGLE_USERNAME together with KAGGLE_KEY

If using kaggle.json, protect it:

chmod 600 ~/.kaggle/kaggle.json

Ask kgnite what it detects:

kgnite doctor
kgnite doctor --json

doctor reports tool availability and authentication state without displaying credential values.

Installation

Recommended: user-local installation

From the repository root:

cd /path/to/kgnite
KGNITE_BIN_DIR="$HOME/.local/bin" bash scripts/install.sh

This method does not require sudo. The installer creates an isolated Python environment under ~/.local/share/kgnite and places the kgnite launcher in ~/.local/bin.

Ensure ~/.local/bin is at the beginning of your PATH:

export PATH="$HOME/.local/bin:$PATH"
hash -r

For Zsh, persist it with:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
hash -r

For Bash, add the same export to ~/.bashrc instead.

System-wide launcher

If you intentionally want the launcher in /usr/local/bin, run:

cd /path/to/kgnite
bash scripts/install.sh

The installer creates the isolated environment and attempts to copy the launcher to /usr/local/bin/kgnite. If that directory is not writable, it prints a command similar to:

sudo install -m 755 "$HOME/.local/share/kgnite/kgnite-launcher" /usr/local/bin/kgnite

Run only the exact command printed for your workstation.

Refresh an existing installation

If kgnite works but newly added commands such as web, setup, or performance are missing, your shell is using an older installed copy. Refresh the isolated installation directly from the current source tree:

cd /path/to/kgnite

"$HOME/.local/share/kgnite/venv/bin/pip" \
  install --upgrade --force-reinstall .

hash -r

The /usr/local/bin/kgnite launcher created by this project points to that same isolated environment, so it normally does not need to be recreated. If you instead installed a user-local launcher, ensure ~/.local/bin precedes /usr/local/bin in PATH.

To diagnose which copy is running:

command -v kgnite
which -a kgnite

Expected locations are usually one of:

~/.local/bin/kgnite
/usr/local/bin/kgnite

If multiple copies are listed, the first one is the command your shell uses.

Development installation

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Verify the installation

command -v kgnite
kgnite --help
kgnite doctor
kgnite setup --help
kgnite performance --help
kgnite trending --help
kgnite web --help
kgnite completions

The top-level help should include at least these newer commands:

setup
template
performance
trending
web

Finally, launch the browser application:

kgnite web

If the command still shows an older feature set, rerun the existing-install refresh and inspect which -a kgnite for another launcher earlier in PATH.

Quick start

# Search and inspect resources
kgnite search datasets "house prices" --sort-by votes
kgnite info dataset zillow/zecon
kgnite files competition titanic

# Download a resource
kgnite download dataset zillow/zecon --output-dir ./downloads

# Preview limited rows from one dataset file
kgnite preview dataset tawfikelmetwally/employee-dataset --rows 10

# Start a competition workspace
kgnite setup titanic --directory ./titanic

# Submit and track results
kgnite submit titanic --file ./submission.csv --message "baseline"
kgnite performance titanic --sync

# Discover currently popular resources
kgnite trending kernels --tag python --limit 20

# Open the local web application
kgnite web

Run kgnite with no arguments for top-level help, or append --help to any command:

kgnite search --help
kgnite setup --help

Local web application

Launch the workstation UI in your default browser:

kgnite web

Select Web guide & examples in the workstation header at any time. It opens a browser-friendly guide in a separate tab while preserving the active local session. The same material is available in WEB_GUIDE.md.

The web application provides forms for:

resource search, trending discovery, tags, keywords, resource-specific filters, sorting, and pagination;
competition workspace setup, overwrite controls, and starter-notebook generation;
score synchronization and performance visualization;
file and notebook-version submissions;
leaderboards, submission history, resource inspection, and paginated file listings;
complete or single-file downloads with cache-refresh controls;
notebook-source pulls;
dataset and model uploads, including KaggleHub and metadata-folder modes;
runtime diagnostics, usage examples, and read-only shell-completion output;
an advanced command runner for other non-interactive option combinations.

The web navigation maps the CLI into these pages:

Web page	CLI capabilities
Discover	`search`, `trending`, and the discovery portion of `browse`
Competition	`setup`, `template`, `performance`, `submit`
Resources	`info`, `files`, `preview`, `download`, `pull-notebook`, `leaderboard`, `submissions`
Uploads	`prepare-notebook`, `push-notebook`, `upload-dataset`, `upload-model`
System	`doctor`, `usage`, and safe `completions --print` output
Advanced	Allowlisted non-interactive commands and uncommon option combinations

The web command is not recursively available inside its own session. The terminal-interactive browse command is represented by the browser-native Discover and Resources pages. Completion installation is intentionally not performed from the web session; the System page can print a completion script without changing shell files.

Commands run on your workstation, in the directory where kgnite web was launched, using your existing Kaggle credentials. Paths entered in the UI are therefore local workstation paths.

The server binds only to 127.0.0.1, uses a random available port by default, and protects API calls with a per-session token. It is not exposed to other computers on the network.

The page sends a local heartbeat while open. After the page is closed and heartbeats stop, the server shuts down automatically. Shutdown allows a 30-second grace period to avoid ending the session during a brief page reload. Press Ctrl+C in the launching terminal for immediate shutdown.

Useful launch options:

# Use a predictable local port
kgnite web --port 8765

# Print the URL without opening a browser
kgnite web --no-browser

# End the server sooner after the page closes
kgnite web --heartbeat-timeout 10

# Allow long downloads or uploads up to 15 minutes
kgnite web --command-timeout 900

The advanced runner parses command arguments without invoking a shell. web, interactive browse, and completion installation are intentionally unavailable through it.

Competition workflow

Workspace settings

kgnite stores persistent settings in ~/.config/kgnite/settings.json. The default workspace is /Users/rajeshsingh/myprojects/kaggle, with separate competitions/ and projects/ folders:

kgnite settings --workspace-dir /Users/rajeshsingh/myprojects/kaggle \
  --competitions-dir competitions \
  --projects-dir projects \
  --kaggle-username rajinh

Running kgnite settings without options displays the effective configuration. Competition setup now defaults to <workspace>/competitions/<slug>.

Create a generic project with Kaggle sources:

kgnite create-project customer-churn \
  --dataset-source owner/reference-data \
  --model-source owner/model/framework/variation

This creates <workspace>/projects/customer-churn with local data, notebooks, submissions, Kaggle notebook bundles, and Kaggle dataset bundles.

Every generated competition or project also contains a tailored README.md describing its folders, local and Kaggle data paths, source metadata, terminal commands, web workflows, publishing order, and troubleshooting steps.

Add or refresh the guide in an existing workspace:

kgnite workspace-help titanic --type competition \
  --directory /Users/rajeshsingh/myprojects/kaggle/competitions/titanic

1. Create a workspace

kgnite setup titanic --directory ./titanic

Interactive mode asks for the competition, metric direction, whether to download data, and whether to generate a notebook. The resulting structure is:

titanic/
├── .titanic-config.json
├── data/
├── notebooks/
│   └── titanic-01.ipynb
└── submissions/

For scripts or CI, provide explicit choices:

kgnite setup titanic \
  --directory ./titanic \
  --metric accuracy \
  --no-lower-is-better \
  --download \
  --template

Use --lower-is-better for loss/error metrics and --no-lower-is-better for accuracy, AUC, F1, and similar metrics. --force permits generated files to be replaced and downloads to be refreshed.

2. Generate or regenerate a notebook

kgnite template titanic \
  --data-dir ./titanic/data \
  --output ./titanic/notebooks/titanic-02.ipynb \
  --participant "Your Name" \
  --notes-page data-description

The notebook identifies the participant and describes itself as a personal competition workspace rather than advertising the generator. By default, it fetches and embeds the official Kaggle data-description page using the supported competition-pages API. The content includes a source link and is sanitized before being written to notebook Markdown.

Add more official pages by repeating --notes-page:

kgnite template titanic \
  --participant "Your Name" \
  --notes-page data-description \
  --notes-page evaluation \
  --notes-page rules

Use --no-competition-notes when generating offline or when page content is not needed. The generated notebook also discovers train, test, and sample-submission CSV files. When a sample submission is available, its columns are documented. Use --force only when replacing an existing notebook is intentional.

3. Prepare and publish a showcase notebook

Preparation copies the notebook and creates Kaggle metadata inside the same competition project. It does not contact Kaggle:

kgnite prepare-notebook ./titanic/notebooks/titanic-01.ipynb \
  --title "Titanic Random Forest" \
  --competition titanic \
  --public

The default bundle is ./titanic/kaggle-notebooks/titanic-random-forest/. Review it, then publish explicitly:

kgnite push-notebook ./titanic/kaggle-notebooks/titanic-random-forest

Generated notebooks automatically use /kaggle/input/titanic on Kaggle and the project data directory locally.

All kernel-metadata.json source lists can be supplied explicitly:

kgnite prepare-notebook ./projects/churn/notebooks/churn-01.ipynb \
  --title "Churn Analysis" \
  --dataset-source owner/reference-data \
  --competition-source playground-competition \
  --kernel-source owner/feature-notebook \
  --model-source owner/model/framework/variation

If you need a different Kaggle account owner than the configured username, add --handle owner/title-slug; when --title is supplied, kgnite derives the slug from the title so Kaggle does not warn about mismatched notebook IDs.

For local data, stage a Kaggle dataset at the same time:

kgnite prepare-notebook ./projects/churn/notebooks/churn-01.ipynb \
  --title "Churn Analysis" \
  --local-dataset ./projects/churn/data \
  --dataset-handle rajinh/churn-project-data \
  --dataset-title "Churn project data"

Publish in dependency order using the returned command. --with-datasets uploads matching staged dataset bundles before pushing the notebook:

kgnite push-notebook ./projects/churn/kaggle-notebooks/churn-analysis --with-datasets

Use --dataset-action version after the dataset already exists. The notebook metadata references the staged dataset handle.

4. Submit a result

File-based competition:

kgnite submit titanic \
  --file ./titanic/submissions/submission.csv \
  --message "random forest baseline"

Code competition:

kgnite submit my-code-competition \
  --kernel my-user/my-notebook \
  --version 3 \
  --message "notebook version 3"

5. Track performance

Fetch current submissions, merge them into local history, and show a score sparkline:

kgnite performance titanic --sync

By default, history is stored in .kgnite/<competition>-scores.json. To use a different file or a lower-is-better metric:

kgnite performance titanic \
  --sync \
  --history ./titanic/scores.json \
  --lower-is-better

Without --sync, the command reads and visualizes existing local history without contacting Kaggle.

Finding Kaggle resources

Search

kgnite search datasets housing --tag tabular --keyword csv
kgnite search kernels rag --language python --kernel-type notebook
kgnite search competitions llm --category playground
kgnite search models gemma --owner google

Repeated --tag and --keyword values are combined: every supplied value must appear somewhere in the returned row metadata.

Options only apply to relevant resources:

Option	Applicable resources	Use it when
`--owner`	models	restricting models to an owner
`--user`	datasets, kernels	restricting results to a Kaggle user
`--category`	competitions	selecting a competition category
`--group`	competitions	selecting general, entered, or in-class competitions
`--language`	kernels	selecting Python, R, SQLite, or Julia
`--kernel-type`	kernels	selecting scripts or notebooks
`--output-type`	kernels	selecting visualization or data outputs
`--dataset`	kernels	finding notebooks attached to a dataset
`--competition`	kernels	finding notebooks attached to a competition

Common sort values accepted by Kaggle include:

Resource	Useful `--sort-by` values
datasets	`hottest`, `votes`, `updated`, `active`
competitions	`grouped`, `prize`, `earliestDeadline`, `latestDeadline`, `numberOfTeams`, `recentlyCreated`
kernels	`hotness`, `commentCount`, `dateCreated`, `dateRun`, `relevance`, `viewCount`, `voteCount`
models	`hotness`, `downloadCount`, `voteCount`, `notebookCount`, `createTime`

Trending and newly added resources

kgnite trending datasets --order popular
kgnite trending datasets --order new --limit 25
kgnite trending competitions --category playground
kgnite trending kernels --search transformer --tag python --keyword pytorch

trending chooses the appropriate Kaggle sort order for each resource type. --order popular is the default; --order new prioritizes recently created or updated resources.

Interactive browsing

kgnite browse
kgnite browse --resource datasets --search titanic --limit 15

The browser guides you through resource selection, search results, and actions such as info, file listing, download, notebook-output download, or notebook-source pull.

Complete command reference

General syntax:

kgnite <command> [arguments] [options]

Most data-returning commands support --json. Use it for scripts, pipelines, and machine-readable output.

`usage`

Print common workflow examples.

kgnite usage

`doctor`

Inspect Kaggle CLI, kagglehub, and authentication state.

kgnite doctor [--json]

Option	When to use it
`--json`	Consume the diagnostic result from a script.

`completions`

Install or print Bash/Zsh completion definitions.

kgnite completions [--shell {bash,zsh}] [--print] [--json]

Option	When to use it
`--shell bash` / `--shell zsh`	Override automatic `$SHELL` detection.
`--print`	Print the completion script instead of installing it.
`--json`	Return installation details as JSON.

`web`

Launch a temporary localhost web application and, by default, open it in the system browser.

kgnite web [--port NUMBER] [--browser | --no-browser]
           [--heartbeat-timeout SECONDS] [--command-timeout SECONDS]

Option	When to use it
`--port NUMBER`	Use a known localhost port; `0` selects an available port automatically.
`--browser`	Open the system default browser; this is the default.
`--no-browser`	Print the local URL for manual opening or headless workstation use.
`--heartbeat-timeout SECONDS`	Change how long the server waits after page heartbeats stop; minimum 5, default 30.
`--command-timeout SECONDS`	Limit each browser-triggered command; default 300 seconds. Increase for large transfers.

Only localhost binding is supported by design. Closing the page ends the server after the heartbeat timeout; Ctrl+C ends it immediately.

`search`

Search datasets, competitions, kernels, or models.

kgnite search {datasets,competitions,kernels,models} [search] [options]

Option	When to use it
`--sort-by VALUE`	Change Kaggle's result ordering.
`--page NUMBER`	Request a result page for datasets, competitions, or kernels.
`--page-size NUMBER`	Set page size for competitions, kernels, or models.
`--owner OWNER`	Filter models by owner.
`--user USER`	Filter datasets or kernels by user.
`--category CATEGORY`	Filter competitions by category.
`--group GROUP`	Filter competitions by group.
`--language LANGUAGE`	Filter kernels by language.
`--kernel-type TYPE`	Filter kernel type, such as `script` or `notebook`.
`--output-type TYPE`	Filter kernel output type.
`--dataset HANDLE`	Find kernels associated with a dataset.
`--competition SLUG`	Find kernels associated with a competition.
`--tag TAG`	Require a returned metadata tag; repeat as needed.
`--keyword WORD`	Require a metadata keyword; repeat as needed.
`--json`	Print the rows as JSON.

`setup`

Create a local competition workspace.

kgnite setup [competition] [options]

Option	When to use it
`--directory PATH`	Choose the workspace path; defaults to the competition slug.
`--metric NAME`	Record the competition metric in `.<competition-slug>-config.json`.
`--lower-is-better`	Mark loss/error-style metrics.
`--no-lower-is-better`	Mark score-style metrics where higher is better.
`--download` / `--no-download`	Explicitly enable or skip the data download.
`--template` / `--no-template`	Explicitly enable or skip starter-notebook creation.
`--force`	Replace generated files and refresh downloads.
`--json`	Use non-interactive defaults and return workspace details as JSON.

`template`

Generate a starter Jupyter notebook.

kgnite template COMPETITION [--output PATH] [--data-dir PATH] [--force] [--json]

Option	When to use it
`--output PATH`	Choose the notebook filename.
`--data-dir PATH`	Point generated code at the competition data directory; defaults to `./data`.
`--participant NAME`	Identify the participant in the notebook; defaults to `KGNITE_PARTICIPANT` or the workstation user.
`--competition-notes` / `--no-competition-notes`	Include or omit official Kaggle competition-page notes. Notes are included by default.
`--notes-page PAGE`	Select a page such as `data-description`, `evaluation`, or `rules`; repeat to include several.
`--force`	Intentionally overwrite an existing notebook.
`--json`	Return the generated path as JSON.

`performance`

Persist and visualize submission scores.

kgnite performance COMPETITION [--sync] [--history PATH] [--lower-is-better] [--json]

Option	When to use it
`--sync`	Fetch Kaggle submissions and merge them into history.
`--history PATH`	Read/write a custom history file.
`--lower-is-better`	Select the minimum score as best.
`--json`	Return summary and score history as JSON.

`trending`

Show popular or newly added resources.

kgnite trending {datasets,competitions,kernels,models} [options]

Option	When to use it
`--order {popular,new}`	Choose popularity or recency; defaults to `popular`.
`--search TEXT`	Narrow the upstream Kaggle query.
`--tag TAG`	Require a tag; repeat as needed.
`--keyword WORD`	Require a keyword; repeat as needed.
`--category CATEGORY`	Restrict competitions to a category.
`--limit NUMBER`	Limit displayed rows; defaults to 10.
`--json`	Print rows as JSON.

`info`

Show resource metadata and related files.

kgnite info {dataset,competition,notebook,model} HANDLE [--json]

Handle examples:

dataset: owner/dataset
competition: competition-slug
notebook: owner/notebook
model: owner/model, owner/model/framework/variation, or a versioned five-part handle

Use --json for machine-readable metadata.

`files`

List files belonging to a resource.

kgnite files {dataset,competition,notebook,model} HANDLE [options]

Option	When to use it
`--page-size NUMBER`	Set the result size for paginated competition/model listings.
`--page-token TOKEN`	Continue a paginated competition/model listing.
`--json`	Print file rows as JSON.

Model file listing requires a version handle such as owner/model/framework/variation/version.

`download`

Download with kagglehub.

kgnite download {dataset,competition,model,notebook-output} HANDLE [options]

Option	When to use it
`--path REMOTE_PATH`	Download one specific file within the resource.
`--output-dir PATH`	Choose the destination directory.
`--force`	Bypass cached content and download again.
`--json`	Return the resolved download path as JSON.

Notebook source is not a notebook output. Use pull-notebook for source code.

`preview`

Preview shape, column names, and limited rows from a Kaggle dataset file, absolute local workstation path, or HTTP/HTTPS URL.

kgnite preview dataset OWNER/DATASET [options]
kgnite preview local /ABSOLUTE/PATH/FILE.csv [options]
kgnite preview url https://example.com/file.csv [options]

Option	When to use it
`--path REMOTE_PATH`	Choose a specific CSV, TSV, JSON, JSONL, NDJSON, or text file. Without it, kgnite selects a small previewable file.
`--rows NUMBER`	Limit displayed records; defaults to 10.
`--columns NUMBER`	Limit displayed columns; defaults to 10.
`--columns all`	Display every detected column while retaining the row limit.
`--max-file-size-mb NUMBER`	Refuse unexpectedly large files; defaults to 25 MB.
`--force`	Refresh the selected file instead of using cached content.
`--json`	Return file metadata and preview rows as JSON.

Every result reports total shape, all detected column names, displayed dimensions, and sample rows. Kaggle preview fetches only the selected file into temporary storage; it does not download the complete dataset. URL preview streams at most the configured size limit. Local preview requires an absolute path. Because shape calculation scans the selected file, that file must fit within the size guard.

In web mode, wide preview tables keep readable column widths and provide horizontal scrolling rather than squeezing every column into the viewport. A hint above the table reports the number of columns and indicates when to scroll.

Examples:

kgnite preview dataset tawfikelmetwally/employee-dataset \
  --path Employee.csv --rows 20 --columns all

kgnite preview local "$HOME/data/employees.csv" \
  --rows 50 --columns 10

kgnite preview url https://example.com/employees.csv \
  --rows 10 --columns all --max-file-size-mb 5

`pull-notebook`

Pull notebook source through the Kaggle CLI.

kgnite pull-notebook OWNER/NOTEBOOK [--output-dir PATH] [--json]

Option	When to use it
`--output-dir PATH`	Select where source files are written.
`--json`	Return Kaggle's result as JSON.

`submit`

Submit a file or notebook version to a competition.

kgnite submit COMPETITION (--file PATH | --kernel HANDLE) --message TEXT [options]

Option	When to use it
`--file PATH`	Submit a local file.
`--kernel HANDLE`	Submit a Kaggle notebook in a code competition.
`--version NUMBER`	Select the notebook version used with `--kernel`.
`--message TEXT`	Required submission description.
`--json`	Return Kaggle's response as JSON.

Provide either --file or --kernel. A notebook --version is only meaningful with --kernel.

`leaderboard`

Show or download a competition leaderboard.

kgnite leaderboard COMPETITION [options]

Option	When to use it
`--show`	Display leaderboard rows in the terminal. This is the default when not downloading.
`--download`	Download the leaderboard file.
`--output-dir PATH`	Choose where the downloaded leaderboard is saved.
`--page-size NUMBER`	Control leaderboard page size.
`--page-token TOKEN`	Continue a paginated result.
`--json`	Print rows or download details as JSON.

`submissions`

List your competition submissions.

kgnite submissions COMPETITION [--json]

Kaggle can reject this request if you have not joined the competition, accepted its rules, or made a submission. kgnite reports these likely causes when the upstream API returns the common access error.

`upload-dataset`

Upload a dataset directory.

kgnite upload-dataset LOCAL_DIR [options]

Option	When to use it
`--handle OWNER/DATASET`	Use direct `kagglehub` upload mode.
`--message TEXT`	Add create/version notes.
`--ignore PATTERN ...`	Exclude files in `kagglehub` mode. Place this option after other options because it accepts multiple values.
`--version`	Run Kaggle CLI dataset-version mode instead of create mode.
`--public`	Make a newly created CLI-mode dataset public.
`--keep-tabular`	Keep tabular files in native form in CLI mode.
`--dir-mode {skip,zip,tar}`	Choose how CLI mode handles subdirectories.
`--delete-old-versions`	Delete old versions during a CLI-mode version upload.
`--json`	Return upload details as JSON.

With --handle, kgnite uses kagglehub. Without it, the local directory must contain metadata expected by the Kaggle CLI.

`upload-model`

Upload a model directory.

kgnite upload-model LOCAL_DIR [options]

Option	When to use it
`--handle OWNER/MODEL/FRAMEWORK/VARIATION`	Use direct `kagglehub` upload mode.
`--message TEXT`	Add model version notes.
`--license-name NAME`	Set the license when creating through `kagglehub`.
`--ignore PATTERN ...`	Exclude files in `kagglehub` mode. Place this option after other options because it accepts multiple values.
`--sigstore`	Enable Sigstore signing in `kagglehub` mode.
`--action {create,update}`	Choose the Kaggle CLI metadata action; defaults to `create`.
`--json`	Return upload details as JSON.

With --handle, kgnite uses kagglehub. Without it, it uses Kaggle CLI metadata mode.

`browse`

Run the interactive search, inspect, and download workflow.

kgnite browse [options]

Option	When to use it
`--resource {datasets,competitions,kernels,models}`	Preselect the resource type.
`--search TEXT`	Supply the initial query.
`--sort-by VALUE`	Choose Kaggle's search ordering.
`--page NUMBER`	Start on a particular page; defaults to 1.
`--page-size NUMBER`	Choose the upstream page size; defaults to 20.
`--limit NUMBER`	Limit rows in the picker; defaults to 10.
`--output-dir PATH`	Set the initial download or notebook-pull destination.

Interactive download choices include the Kaggle cache, current directory, or a custom directory. Resource-specific subdirectories prevent unrelated downloads from colliding.

Shell completions

Install or refresh completions for the detected shell on the current workstation:

kgnite completions

Or choose a shell explicitly:

kgnite completions --shell zsh
kgnite completions --shell bash

Generated files are stored under ~/.local/share/kgnite/completions:

Zsh: ~/.local/share/kgnite/completions/_kgnite
Bash: ~/.local/share/kgnite/completions/kgnite.bash

The command prints the exact line to run immediately and the line to add to your shell config. For example:

# zsh: enable immediately in the current terminal
fpath=("$HOME/.local/share/kgnite/completions" $fpath); autoload -Uz compinit && compinit

# bash: enable immediately in the current terminal
source "$HOME/.local/share/kgnite/completions/kgnite.bash"

To persist completions, add the printed line to ~/.zshrc or ~/.bashrc, then open a new terminal or source that file:

source ~/.zshrc
# or
source ~/.bashrc

After upgrading or reinstalling kgnite, run kgnite completions again. This rewrites the completion file with the current command set, including newly added commands such as settings, create-project, workspace-help, prepare-notebook, and push-notebook.

On another workstation, install or update kgnite first, then run the same command there:

cd /path/to/kgnite
bash scripts/install.sh
kgnite completions

For read-only environments or manual installation, print the script instead of installing it:

mkdir -p ~/.local/share/kgnite/completions
kgnite completions --shell zsh --print > ~/.local/share/kgnite/completions/_kgnite
kgnite completions --shell bash --print > ~/.local/share/kgnite/completions/kgnite.bash

The web app can print completion scripts from the System page, but it intentionally does not modify shell configuration files from the browser.

Maintenance and development

Reinstall after changing the source:

"$HOME/.local/share/kgnite/venv/bin/pip" \
  install --upgrade --force-reinstall .
hash -r

Alternatively, rerun scripts/install.sh with the same KGNITE_BIN_DIR used for the original installation.

Run the project checks:

PYTHONPATH=src python3 -m unittest discover -s tests -v
ruff check src tests
ruff format --check src tests

Available Make targets:

make install
make reinstall
make uninstall
make dev
make completions

Uninstall:

bash scripts/uninstall.sh

Troubleshooting

New commands are missing after an update

Check the resolved launcher and all duplicates:

command -v kgnite
which -a kgnite

Then refresh the installed environment from the repository root:

"$HOME/.local/share/kgnite/venv/bin/pip" \
  install --upgrade --force-reinstall .
hash -r
kgnite web --help

If which -a lists both ~/.local/bin/kgnite and /usr/local/bin/kgnite, ensure the intended directory appears first in PATH.

`No module named kagglesdk.competitions.legacy`

The kagglesdk 0.1.32 wheel is missing a package imported by its own competition client. The project excludes that broken release. Reinstall from the repository root so the dependency resolver selects a working SDK version:

"$HOME/.local/share/kgnite/venv/bin/pip" \
  install --upgrade --force-reinstall .
hash -r
kgnite --help

Confirm the resolved version if necessary:

"$HOME/.local/share/kgnite/venv/bin/pip" show kagglesdk

It must not report version 0.1.32.

`kaggle` is not installed or not on `PATH`

Install the Kaggle CLI, then confirm kaggle --version works in the same shell used for kgnite.

Authentication is missing

Export KAGGLE_API_TOKEN, configure kaggle.json, and rerun:

kgnite doctor

Submission history is unavailable

Open the competition page, join the competition, accept its rules, and make at least one submission before retrying kgnite submissions or kgnite performance --sync.

A generated file already exists

setup and template protect existing generated files. Review the file first, then use --force only when replacement is intended.

Model handles fail

Use the full handle required by the operation. Model downloads and file listings are most reliable with a versioned handle:

owner/model/framework/variation/version

JSON output is needed for automation

Use --json where supported. In setup, JSON mode also avoids optional interactive questions and uses safe defaults unless explicit flags are supplied.

The web page does not open automatically

Copy the URL printed by kgnite web into any local browser, or launch with kgnite web --no-browser. If a selected port is occupied, omit --port to let kgnite choose an available one.

A web operation times out

Large downloads and uploads can exceed the default five-minute command limit. Restart with a larger value, for example kgnite web --command-timeout 1800.

Name		Name	Last commit message	Last commit date
Latest commit History 10 Commits
build/lib/kgnite		build/lib/kgnite
completions		completions
scripts		scripts
src/kgnite		src/kgnite
tests		tests
.gitignore		.gitignore
LICENSE		LICENSE
Makefile		Makefile
QUICKSTART.md		QUICKSTART.md
README.md		README.md
WEB_GUIDE.md		WEB_GUIDE.md
pyproject.toml		pyproject.toml

Folders and files

Latest commit

History

Repository files navigation

kgnite

Contents

Requirements

Authentication

Installation

Recommended: user-local installation

System-wide launcher

Refresh an existing installation

Development installation

Verify the installation

Quick start

Local web application

Competition workflow

Workspace settings

1. Create a workspace

2. Generate or regenerate a notebook

3. Prepare and publish a showcase notebook

4. Submit a result

5. Track performance

Finding Kaggle resources

Search

Trending and newly added resources

Interactive browsing

Complete command reference

usage

doctor

completions

web

search

setup

template

performance

trending

info

files

download

preview

pull-notebook

submit

leaderboard

submissions

upload-dataset

upload-model

browse