feat(kernels): add kernels run command

[sridipbasu]

Summary

This adds a new kaggle kernels run command that pushes a kernel to Kaggle and waits for the run to finish instead of returning immediately like kernels push does.

This is useful when using Kaggle notebooks as part of scripts or CI workflows, where manually running kernels status in a loop is not very convenient.

For example:

kaggle kernels run -p . --output ./results

The command waits for the kernel to complete, returns a non-zero exit code if the run fails, and can optionally download the output files.

What changed

Added a new kernels run command with support for:

• Waiting for the kernel to finish with --wait-timeout and --poll-interval.
• Downloading outputs with --output.
• Filtering outputs with --file-pattern.
• Overwriting existing output files with --force.
• Proper exit codes for successful and failed runs.
• A stale-session check so an older completed session is not immediately treated as the new run.
• Useful recovery information when the wait is interrupted or times out.

The implementation reuses the existing polling/backoff and kernel output functionality instead of introducing a separate polling system.

API limitation

While working on this, I also checked whether the run could be pinned to the exact kernel version returned by the push API.

The SDK exposes a versionLabel field, but testing it against the actual Kaggle API showed that it currently returns a 404 for real kernel versions. Because of this, the command uses the latest-session API with a pre-push baseline check rather than relying on versionLabel.

This also means that running multiple versions of the same kernel at the same time is not supported by this command for now.

Tests

Added unit tests covering the kernel run state flow, including successful runs, failures, timeouts, transient API errors, stale sessions, validation, output handling, and CLI parsing.

Also added a backend test and manually verified the command against the live Kaggle API with both a successful and a failing kernel.

Ran:

pytest tests/unit/test_kernels_run.py tests/unit/test_cli_kernels.py

pytest tests/unit

black --check on the modified files

The full unit suite passes with 1319 tests passing.

The live validation also confirmed:

• Successful kernel → outputs downloaded → exit code 0
• Failed kernel → error reported → exit code 1

[stevemessick]

@sridipbasu Thanks for this. I'm not sure we can use it, though. I'll have to take a closer look than I have time for right now. The issue is that we've been talking for some time (like, years) about adopting Google's long-running operations pattern (https://google.aip.dev/151). The time for doing that work appears to be getting closer (although it isn't scheduled yet). I don't want to introduce a new feature that would cause backward-compatibility problems with planned improvements. So, we have to be sure there won't be any signals to users (either CLI or Python library) that would change between implementations.

[sridipbasu]

@stevemessick
Hmm got it thanks. I was looking at the Operation side of things in the SDK as part of this and can appreciate the desire to steer clear of any new additions that would be at odds with the LRO work.

I'd just like to have some sense of the timeline on that front. Is the LRO work set to be a priority in an imminent release or is it still a ways off? Should it come up in the near term, I have no objection to putting this aside for now and coming back to it when the time is right.

[stevemessick]

@sridipbasu I expect LRO to be in the next major release. It does require some backend work, obviously. We don't know when it will happen but I suspect (vague, intentionally) it will be in 2026. I think it is unlikely to be in Q3, though, just because there are a number of other changes in the works. The big one is refactoring kaggle_api_extended.py, which I think you'll agree is long overdue.