kdev-cli 0.1.3__tar.gz → 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (67) hide show
  1. kdev_cli-0.2.0/.gitignore +14 -0
  2. kdev_cli-0.2.0/PKG-INFO +195 -0
  3. kdev_cli-0.2.0/README.md +162 -0
  4. {kdev_cli-0.1.3 → kdev_cli-0.2.0}/pyproject.toml +16 -3
  5. {kdev_cli-0.1.3 → kdev_cli-0.2.0}/src/kdev/api.py +125 -24
  6. kdev_cli-0.2.0/src/kdev/auth.py +254 -0
  7. {kdev_cli-0.1.3 → kdev_cli-0.2.0}/src/kdev/bootstrap.py +47 -0
  8. {kdev_cli-0.1.3 → kdev_cli-0.2.0}/src/kdev/cli.py +85 -22
  9. {kdev_cli-0.1.3 → kdev_cli-0.2.0}/src/kdev/cloudflared.py +7 -6
  10. {kdev_cli-0.1.3 → kdev_cli-0.2.0}/src/kdev/commands/_common.py +9 -6
  11. {kdev_cli-0.1.3 → kdev_cli-0.2.0}/src/kdev/commands/account.py +21 -5
  12. {kdev_cli-0.1.3 → kdev_cli-0.2.0}/src/kdev/commands/box.py +505 -91
  13. kdev_cli-0.2.0/src/kdev/commands/doctor.py +189 -0
  14. kdev_cli-0.2.0/src/kdev/commands/home.py +399 -0
  15. {kdev_cli-0.1.3 → kdev_cli-0.2.0}/src/kdev/commands/settings.py +35 -5
  16. {kdev_cli-0.1.3 → kdev_cli-0.2.0}/src/kdev/commands/tunnel.py +17 -12
  17. {kdev_cli-0.1.3 → kdev_cli-0.2.0}/src/kdev/commands/workspace.py +41 -10
  18. {kdev_cli-0.1.3 → kdev_cli-0.2.0}/src/kdev/config.py +13 -0
  19. {kdev_cli-0.1.3 → kdev_cli-0.2.0}/src/kdev/errors.py +12 -0
  20. {kdev_cli-0.1.3 → kdev_cli-0.2.0}/src/kdev/kdev_box.py +14 -0
  21. kdev_cli-0.2.0/src/kdev/menu.py +372 -0
  22. {kdev_cli-0.1.3 → kdev_cli-0.2.0}/src/kdev/notebook.py +55 -22
  23. {kdev_cli-0.1.3 → kdev_cli-0.2.0}/src/kdev/persistence.py +218 -16
  24. {kdev_cli-0.1.3 → kdev_cli-0.2.0}/src/kdev/quota.py +34 -2
  25. {kdev_cli-0.1.3 → kdev_cli-0.2.0}/src/kdev/safety.py +18 -1
  26. kdev_cli-0.2.0/src/kdev/session.py +536 -0
  27. kdev_cli-0.2.0/src/kdev/sshcfg.py +118 -0
  28. kdev_cli-0.2.0/src/kdev/ui.py +1493 -0
  29. {kdev_cli-0.1.3 → kdev_cli-0.2.0}/src/kdev/wizard.py +10 -4
  30. kdev_cli-0.2.0/tests/conftest.py +86 -0
  31. kdev_cli-0.2.0/tests/test_account.py +56 -0
  32. kdev_cli-0.2.0/tests/test_api.py +275 -0
  33. kdev_cli-0.2.0/tests/test_api_errors.py +55 -0
  34. kdev_cli-0.2.0/tests/test_auth.py +307 -0
  35. {kdev_cli-0.1.3 → kdev_cli-0.2.0}/tests/test_bootstrap.py +112 -3
  36. {kdev_cli-0.1.3 → kdev_cli-0.2.0}/tests/test_cli.py +702 -28
  37. kdev_cli-0.2.0/tests/test_concurrent_start.py +401 -0
  38. kdev_cli-0.2.0/tests/test_hermetic.py +28 -0
  39. {kdev_cli-0.1.3 → kdev_cli-0.2.0}/tests/test_kdev_box.py +25 -0
  40. kdev_cli-0.2.0/tests/test_menu.py +93 -0
  41. kdev_cli-0.2.0/tests/test_notebook.py +382 -0
  42. kdev_cli-0.2.0/tests/test_persistence.py +562 -0
  43. kdev_cli-0.2.0/tests/test_sshcfg.py +214 -0
  44. kdev_cli-0.2.0/tests/test_ui.py +527 -0
  45. kdev_cli-0.2.0/website/README.md +40 -0
  46. kdev_cli-0.1.3/.gitignore +0 -11
  47. kdev_cli-0.1.3/PKG-INFO +0 -598
  48. kdev_cli-0.1.3/README.md +0 -567
  49. kdev_cli-0.1.3/src/kdev/auth.py +0 -115
  50. kdev_cli-0.1.3/src/kdev/commands/doctor.py +0 -127
  51. kdev_cli-0.1.3/src/kdev/commands/home.py +0 -92
  52. kdev_cli-0.1.3/src/kdev/session.py +0 -284
  53. kdev_cli-0.1.3/src/kdev/sshcfg.py +0 -72
  54. kdev_cli-0.1.3/src/kdev/ui.py +0 -666
  55. kdev_cli-0.1.3/tests/test_api.py +0 -96
  56. kdev_cli-0.1.3/tests/test_auth.py +0 -64
  57. kdev_cli-0.1.3/tests/test_notebook.py +0 -216
  58. kdev_cli-0.1.3/tests/test_persistence.py +0 -258
  59. kdev_cli-0.1.3/tests/test_sshcfg.py +0 -44
  60. kdev_cli-0.1.3/tests/test_ui.py +0 -142
  61. {kdev_cli-0.1.3 → kdev_cli-0.2.0}/LICENSE +0 -0
  62. {kdev_cli-0.1.3 → kdev_cli-0.2.0}/src/kdev/__init__.py +0 -0
  63. {kdev_cli-0.1.3 → kdev_cli-0.2.0}/src/kdev/__main__.py +0 -0
  64. {kdev_cli-0.1.3 → kdev_cli-0.2.0}/src/kdev/commands/__init__.py +0 -0
  65. {kdev_cli-0.1.3 → kdev_cli-0.2.0}/src/kdev/tunnel.py +0 -0
  66. {kdev_cli-0.1.3 → kdev_cli-0.2.0}/tests/test_config.py +0 -0
  67. {kdev_cli-0.1.3 → kdev_cli-0.2.0}/tests/test_tunnel.py +0 -0
@@ -0,0 +1,14 @@
1
+ .venv/
2
+ __pycache__/
3
+ *.py[cod]
4
+ *.egg-info/
5
+ dist/
6
+ build/
7
+ .pytest_cache/
8
+ .ruff_cache/
9
+ .coverage
10
+ htmlcov/
11
+ .DS_Store
12
+
13
+ # Design kit fetched for the website build-out (Leonxlnx/taste-skill, MIT); local only.
14
+ .agents/skills/design-taste-frontend/
@@ -0,0 +1,195 @@
1
+ Metadata-Version: 2.5
2
+ Name: kdev-cli
3
+ Version: 0.2.0
4
+ Summary: A Kaggle notebook as your remote dev box: SSH and VS Code in, files that persist across sessions, accounts and machines.
5
+ Project-URL: Homepage, https://kdev-cli.pages.dev
6
+ Project-URL: Documentation, https://kdev-cli.pages.dev/docs/
7
+ Project-URL: Repository, https://github.com/tushar-mahalya/kdev
8
+ Project-URL: Issues, https://github.com/tushar-mahalya/kdev/issues
9
+ Project-URL: Changelog, https://github.com/tushar-mahalya/kdev/blob/main/CHANGELOG.md
10
+ License: MIT
11
+ License-File: LICENSE
12
+ Keywords: cloudflare-tunnel,gpu,kaggle,remote-development,ssh,vscode
13
+ Classifier: Development Status :: 4 - Beta
14
+ Classifier: Environment :: Console
15
+ Classifier: Intended Audience :: Developers
16
+ Classifier: Intended Audience :: Science/Research
17
+ Classifier: License :: OSI Approved :: MIT License
18
+ Classifier: Operating System :: MacOS
19
+ Classifier: Operating System :: POSIX :: Linux
20
+ Classifier: Programming Language :: Python :: 3
21
+ Classifier: Programming Language :: Python :: 3.11
22
+ Classifier: Programming Language :: Python :: 3.12
23
+ Classifier: Programming Language :: Python :: 3.13
24
+ Classifier: Topic :: Software Development
25
+ Requires-Python: >=3.11
26
+ Requires-Dist: httpx<1,>=0.27
27
+ Requires-Dist: kaggle<3,>=2.2
28
+ Requires-Dist: prompt-toolkit<4,>=3.0.36
29
+ Requires-Dist: questionary<3,>=2.0
30
+ Requires-Dist: rich<16,>=13
31
+ Requires-Dist: typer<1,>=0.27
32
+ Description-Content-Type: text/markdown
33
+
34
+ <p align="center">
35
+ <img src="https://raw.githubusercontent.com/tushar-mahalya/kdev/main/docs/assets/kdev-logo.png" alt="kdev" width="520">
36
+ </p>
37
+
38
+ <p align="center">
39
+ <b>A Kaggle notebook as your remote dev box.</b><br>
40
+ Start it with one command, work in it from VS Code or a shell, and leave whenever you like.<br>
41
+ Your files are there next time — on any account in your Kaggle group, from any machine.
42
+ </p>
43
+
44
+ <p align="center">
45
+ <a href="https://github.com/tushar-mahalya/kdev/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/tushar-mahalya/kdev/actions/workflows/ci.yml/badge.svg"></a>
46
+ <a href="https://pypi.org/project/kdev-cli/"><img alt="PyPI" src="https://img.shields.io/pypi/v/kdev-cli?logo=pypi&logoColor=white&color=00b8d4"></a>
47
+ <a href="https://pypi.org/project/kdev-cli/"><img alt="Python versions" src="https://img.shields.io/pypi/pyversions/kdev-cli?logo=python&logoColor=white&color=3776AB"></a>
48
+ <a href="https://github.com/tushar-mahalya/kdev/releases/latest"><img alt="Latest release" src="https://img.shields.io/github/v/release/tushar-mahalya/kdev?label=release&logo=github&color=2ea44f"></a>
49
+ <a href="https://github.com/tushar-mahalya/kdev/blob/main/LICENSE"><img alt="MIT license" src="https://img.shields.io/badge/license-MIT-2ea44f"></a>
50
+ <a href="https://scorecard.dev/viewer/?uri=github.com/tushar-mahalya/kdev"><img alt="OpenSSF Scorecard" src="https://api.scorecard.dev/projects/github.com/tushar-mahalya/kdev/badge"></a>
51
+ <a href="https://kdev-cli.pages.dev"><img alt="Website" src="https://img.shields.io/badge/website-kdev--cli.pages.dev-00b8d4"></a>
52
+ <a href="https://github.com/tushar-mahalya/kdev/blob/main/CONTRIBUTING.md"><img alt="PRs welcome" src="https://img.shields.io/badge/PRs-welcome-00b8d4"></a>
53
+ </p>
54
+
55
+ <p align="center">
56
+ <a href="https://kdev-cli.pages.dev"><b>Website</b></a> ·
57
+ <a href="https://kdev-cli.pages.dev/docs/">Docs</a> ·
58
+ <a href="https://kdev-cli.pages.dev/docs/how-it-works/">How it works</a> ·
59
+ <a href="https://kdev-cli.pages.dev/docs/commands/">Commands</a> ·
60
+ <a href="https://github.com/tushar-mahalya/kdev/blob/main/CHANGELOG.md">Changelog</a>
61
+ </p>
62
+
63
+ ## Why kdev
64
+
65
+ Kaggle gives every account free GPU hours, but only inside a notebook. kdev
66
+ turns that notebook into a machine you can `ssh` into or open in VS Code.
67
+
68
+ - **One box, pooled quota.** Every account in your Kaggle group runs the same
69
+ shared notebook on its own weekly GPU hours. When one runs short, `kdev up`
70
+ asks which account takes over.
71
+ - **Files that persist.** Whatever is in `/kaggle/working` when a session ends
72
+ comes back at the next start, however it ended: `kdev down`, a timeout, a
73
+ crash, your wifi dropping.
74
+ - **A real server.** A stable hostname over Cloudflare Tunnel, public-key SSH,
75
+ and your notebook's full environment (CUDA, Python, Kaggle variables).
76
+ No port is opened on the box.
77
+
78
+ ## Install
79
+
80
+ Needs Python 3.11+, `ssh`, and a Kaggle account in a Kaggle group.
81
+
82
+ ```bash
83
+ uv tool install kdev-cli # or: pipx install kdev-cli
84
+ ```
85
+
86
+ The package is `kdev-cli`; the command it installs is `kdev`. Upgrade with
87
+ `uv tool upgrade kdev-cli`.
88
+
89
+ ## Quick start
90
+
91
+ ```bash
92
+ kdev setup # once per machine: SSH key, cloudflared, Kaggle sign-in, workspace, tunnel
93
+ kdev up # start the box, or connect to the one already running
94
+ ssh kaggle # or VS Code → Remote-SSH → kaggle
95
+ kdev down # optional: stop early and hand the quota back
96
+ ```
97
+
98
+ `kdev setup` only does what is missing, so it is safe to run again. Two parts
99
+ of it you may want to run on their own:
100
+
101
+ - **The tunnel.** With a domain on Cloudflare, `kdev tunnel setup` creates a
102
+ named tunnel with a hostname that never changes. Without one, `kdev setup`
103
+ offers a free quick tunnel, on a new hostname each session.
104
+ - **The workspace.** One account owns the notebook and shares it with the
105
+ group: `kdev workspace create --group <your-group-slug>`, once. Everyone else
106
+ runs `kdev workspace join`.
107
+
108
+ Leaving needs no ceremony: close the laptop and walk away. The box runs to the
109
+ end of its session and saves as it stops.
110
+
111
+ ## Everyday commands
112
+
113
+ | command | what it does |
114
+ |---|---|
115
+ | `kdev` | the home screen: the box and every account's quota, live; one key per action |
116
+ | `kdev up` | start the box, or connect to the running one |
117
+ | `kdev down` | stop the box; files are saved however it stops |
118
+ | `kdev ssh` | open a shell on the box |
119
+ | `kdev status` | running? who started it? when does it end? files back? |
120
+ | `kdev forward PORT` | reach a service on the box through localhost (`9000:8888` remaps) |
121
+ | `kdev logs` | stream the session's log |
122
+ | `kdev history` | past saved sessions, who ran them and how they ended |
123
+ | `kdev restore` | finish or repeat the restore of your saved files |
124
+ | `kdev backup` | copy the running box's files to this machine |
125
+ | `kdev account` | accounts and their GPU/TPU hours left (`add`, `use`, `remove`) |
126
+ | `kdev workspace` | the shared notebook (`files`, `join`, `use`, `create`, `share`) |
127
+ | `kdev doctor` | check everything kdev depends on |
128
+
129
+ Run bare `kdev` and press a key: `1` starts the box, `s` shows its status, `q`
130
+ quits. The highlighted item always shows the command it runs, so everything
131
+ the menu does you can also type or script.
132
+
133
+ Useful flags on `kdev up`: `--gpu none|t4|p100|tpu`, `--hours N`,
134
+ `--account NAME`, `--open code|shell|none`, `--no-restore`, `--replace`, `-y`.
135
+ Add `-v` to any command to log each Kaggle API call. `status`, `history`,
136
+ `account` and `workspace files` take `--json` for scripts.
137
+ See the [full command reference](https://kdev-cli.pages.dev/docs/commands/).
138
+
139
+ ## Settings
140
+
141
+ Pick once with `kdev config set`, and `kdev up` stops asking:
142
+
143
+ ```bash
144
+ kdev config set gpu t4 # none, t4, p100, tpu (and l4, a100, h100 where available)
145
+ kdev config set hours 9 # Kaggle's limit: 12h, 9h on TPU
146
+ kdev config # list every setting; secrets are never shown
147
+ ```
148
+
149
+ Other settings cover a git remote that the box clones at boot and pushes every
150
+ 15 minutes, your SSH key and alias, and the tunnel. They are stored in
151
+ `~/.config/kdev/config.json` (mode 0600). All of them:
152
+ [Settings](https://kdev-cli.pages.dev/docs/settings/).
153
+
154
+ ## Troubleshooting
155
+
156
+ ```bash
157
+ kdev doctor # every dependency, account token, the workspace and the tunnel's DNS
158
+ kdev -v status # the same command, with each Kaggle API call logged
159
+ kdev logs # what the box itself is saying
160
+ ```
161
+
162
+ Most messages name the command that fixes them. Common ones are listed in
163
+ [Troubleshooting](https://kdev-cli.pages.dev/docs/troubleshooting/).
164
+
165
+ ## Documentation
166
+
167
+ - [Install and set up](https://kdev-cli.pages.dev/docs/): the tunnel and the workspace in detail
168
+ - [How it works](https://kdev-cli.pages.dev/docs/how-it-works/): the architecture, what `kdev up` does, how files persist, with diagrams
169
+ - [Your files](https://kdev-cli.pages.dev/docs/files/) and [Several accounts, several machines](https://kdev-cli.pages.dev/docs/accounts/)
170
+ - [Security and limits](https://kdev-cli.pages.dev/docs/security/)
171
+ - [Architecture for contributors](https://github.com/tushar-mahalya/kdev/blob/main/docs/ARCHITECTURE.md), including how the code is laid out
172
+
173
+ ## Contributing
174
+
175
+ Bug reports, fixes, docs and features are welcome. For anything bigger than a
176
+ fix, open an issue first. Questions go to
177
+ [Discussions](https://github.com/tushar-mahalya/kdev/discussions). How to set
178
+ up, test without spending GPU quota, and send a pull request:
179
+ [CONTRIBUTING.md](https://github.com/tushar-mahalya/kdev/blob/main/CONTRIBUTING.md).
180
+
181
+ ## Security
182
+
183
+ Access is public-key SSH only. Kaggle has no API for notebook Secrets, so the
184
+ tunnel credentials sit in the private notebook's source, readable by anyone
185
+ with Can Edit. Kaggle allows one account per person and restricts tunnelling
186
+ out of notebooks; know the rules you are working under. Details are in
187
+ [Security and limits](https://kdev-cli.pages.dev/docs/security/). Report a
188
+ vulnerability privately, as
189
+ [SECURITY.md](https://github.com/tushar-mahalya/kdev/blob/main/SECURITY.md)
190
+ describes.
191
+
192
+ ## License
193
+
194
+ [MIT](https://github.com/tushar-mahalya/kdev/blob/main/LICENSE). kdev is an
195
+ independent project, not affiliated with Kaggle, Google or Cloudflare.
@@ -0,0 +1,162 @@
1
+ <p align="center">
2
+ <img src="https://raw.githubusercontent.com/tushar-mahalya/kdev/main/docs/assets/kdev-logo.png" alt="kdev" width="520">
3
+ </p>
4
+
5
+ <p align="center">
6
+ <b>A Kaggle notebook as your remote dev box.</b><br>
7
+ Start it with one command, work in it from VS Code or a shell, and leave whenever you like.<br>
8
+ Your files are there next time — on any account in your Kaggle group, from any machine.
9
+ </p>
10
+
11
+ <p align="center">
12
+ <a href="https://github.com/tushar-mahalya/kdev/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/tushar-mahalya/kdev/actions/workflows/ci.yml/badge.svg"></a>
13
+ <a href="https://pypi.org/project/kdev-cli/"><img alt="PyPI" src="https://img.shields.io/pypi/v/kdev-cli?logo=pypi&logoColor=white&color=00b8d4"></a>
14
+ <a href="https://pypi.org/project/kdev-cli/"><img alt="Python versions" src="https://img.shields.io/pypi/pyversions/kdev-cli?logo=python&logoColor=white&color=3776AB"></a>
15
+ <a href="https://github.com/tushar-mahalya/kdev/releases/latest"><img alt="Latest release" src="https://img.shields.io/github/v/release/tushar-mahalya/kdev?label=release&logo=github&color=2ea44f"></a>
16
+ <a href="https://github.com/tushar-mahalya/kdev/blob/main/LICENSE"><img alt="MIT license" src="https://img.shields.io/badge/license-MIT-2ea44f"></a>
17
+ <a href="https://scorecard.dev/viewer/?uri=github.com/tushar-mahalya/kdev"><img alt="OpenSSF Scorecard" src="https://api.scorecard.dev/projects/github.com/tushar-mahalya/kdev/badge"></a>
18
+ <a href="https://kdev-cli.pages.dev"><img alt="Website" src="https://img.shields.io/badge/website-kdev--cli.pages.dev-00b8d4"></a>
19
+ <a href="https://github.com/tushar-mahalya/kdev/blob/main/CONTRIBUTING.md"><img alt="PRs welcome" src="https://img.shields.io/badge/PRs-welcome-00b8d4"></a>
20
+ </p>
21
+
22
+ <p align="center">
23
+ <a href="https://kdev-cli.pages.dev"><b>Website</b></a> ·
24
+ <a href="https://kdev-cli.pages.dev/docs/">Docs</a> ·
25
+ <a href="https://kdev-cli.pages.dev/docs/how-it-works/">How it works</a> ·
26
+ <a href="https://kdev-cli.pages.dev/docs/commands/">Commands</a> ·
27
+ <a href="https://github.com/tushar-mahalya/kdev/blob/main/CHANGELOG.md">Changelog</a>
28
+ </p>
29
+
30
+ ## Why kdev
31
+
32
+ Kaggle gives every account free GPU hours, but only inside a notebook. kdev
33
+ turns that notebook into a machine you can `ssh` into or open in VS Code.
34
+
35
+ - **One box, pooled quota.** Every account in your Kaggle group runs the same
36
+ shared notebook on its own weekly GPU hours. When one runs short, `kdev up`
37
+ asks which account takes over.
38
+ - **Files that persist.** Whatever is in `/kaggle/working` when a session ends
39
+ comes back at the next start, however it ended: `kdev down`, a timeout, a
40
+ crash, your wifi dropping.
41
+ - **A real server.** A stable hostname over Cloudflare Tunnel, public-key SSH,
42
+ and your notebook's full environment (CUDA, Python, Kaggle variables).
43
+ No port is opened on the box.
44
+
45
+ ## Install
46
+
47
+ Needs Python 3.11+, `ssh`, and a Kaggle account in a Kaggle group.
48
+
49
+ ```bash
50
+ uv tool install kdev-cli # or: pipx install kdev-cli
51
+ ```
52
+
53
+ The package is `kdev-cli`; the command it installs is `kdev`. Upgrade with
54
+ `uv tool upgrade kdev-cli`.
55
+
56
+ ## Quick start
57
+
58
+ ```bash
59
+ kdev setup # once per machine: SSH key, cloudflared, Kaggle sign-in, workspace, tunnel
60
+ kdev up # start the box, or connect to the one already running
61
+ ssh kaggle # or VS Code → Remote-SSH → kaggle
62
+ kdev down # optional: stop early and hand the quota back
63
+ ```
64
+
65
+ `kdev setup` only does what is missing, so it is safe to run again. Two parts
66
+ of it you may want to run on their own:
67
+
68
+ - **The tunnel.** With a domain on Cloudflare, `kdev tunnel setup` creates a
69
+ named tunnel with a hostname that never changes. Without one, `kdev setup`
70
+ offers a free quick tunnel, on a new hostname each session.
71
+ - **The workspace.** One account owns the notebook and shares it with the
72
+ group: `kdev workspace create --group <your-group-slug>`, once. Everyone else
73
+ runs `kdev workspace join`.
74
+
75
+ Leaving needs no ceremony: close the laptop and walk away. The box runs to the
76
+ end of its session and saves as it stops.
77
+
78
+ ## Everyday commands
79
+
80
+ | command | what it does |
81
+ |---|---|
82
+ | `kdev` | the home screen: the box and every account's quota, live; one key per action |
83
+ | `kdev up` | start the box, or connect to the running one |
84
+ | `kdev down` | stop the box; files are saved however it stops |
85
+ | `kdev ssh` | open a shell on the box |
86
+ | `kdev status` | running? who started it? when does it end? files back? |
87
+ | `kdev forward PORT` | reach a service on the box through localhost (`9000:8888` remaps) |
88
+ | `kdev logs` | stream the session's log |
89
+ | `kdev history` | past saved sessions, who ran them and how they ended |
90
+ | `kdev restore` | finish or repeat the restore of your saved files |
91
+ | `kdev backup` | copy the running box's files to this machine |
92
+ | `kdev account` | accounts and their GPU/TPU hours left (`add`, `use`, `remove`) |
93
+ | `kdev workspace` | the shared notebook (`files`, `join`, `use`, `create`, `share`) |
94
+ | `kdev doctor` | check everything kdev depends on |
95
+
96
+ Run bare `kdev` and press a key: `1` starts the box, `s` shows its status, `q`
97
+ quits. The highlighted item always shows the command it runs, so everything
98
+ the menu does you can also type or script.
99
+
100
+ Useful flags on `kdev up`: `--gpu none|t4|p100|tpu`, `--hours N`,
101
+ `--account NAME`, `--open code|shell|none`, `--no-restore`, `--replace`, `-y`.
102
+ Add `-v` to any command to log each Kaggle API call. `status`, `history`,
103
+ `account` and `workspace files` take `--json` for scripts.
104
+ See the [full command reference](https://kdev-cli.pages.dev/docs/commands/).
105
+
106
+ ## Settings
107
+
108
+ Pick once with `kdev config set`, and `kdev up` stops asking:
109
+
110
+ ```bash
111
+ kdev config set gpu t4 # none, t4, p100, tpu (and l4, a100, h100 where available)
112
+ kdev config set hours 9 # Kaggle's limit: 12h, 9h on TPU
113
+ kdev config # list every setting; secrets are never shown
114
+ ```
115
+
116
+ Other settings cover a git remote that the box clones at boot and pushes every
117
+ 15 minutes, your SSH key and alias, and the tunnel. They are stored in
118
+ `~/.config/kdev/config.json` (mode 0600). All of them:
119
+ [Settings](https://kdev-cli.pages.dev/docs/settings/).
120
+
121
+ ## Troubleshooting
122
+
123
+ ```bash
124
+ kdev doctor # every dependency, account token, the workspace and the tunnel's DNS
125
+ kdev -v status # the same command, with each Kaggle API call logged
126
+ kdev logs # what the box itself is saying
127
+ ```
128
+
129
+ Most messages name the command that fixes them. Common ones are listed in
130
+ [Troubleshooting](https://kdev-cli.pages.dev/docs/troubleshooting/).
131
+
132
+ ## Documentation
133
+
134
+ - [Install and set up](https://kdev-cli.pages.dev/docs/): the tunnel and the workspace in detail
135
+ - [How it works](https://kdev-cli.pages.dev/docs/how-it-works/): the architecture, what `kdev up` does, how files persist, with diagrams
136
+ - [Your files](https://kdev-cli.pages.dev/docs/files/) and [Several accounts, several machines](https://kdev-cli.pages.dev/docs/accounts/)
137
+ - [Security and limits](https://kdev-cli.pages.dev/docs/security/)
138
+ - [Architecture for contributors](https://github.com/tushar-mahalya/kdev/blob/main/docs/ARCHITECTURE.md), including how the code is laid out
139
+
140
+ ## Contributing
141
+
142
+ Bug reports, fixes, docs and features are welcome. For anything bigger than a
143
+ fix, open an issue first. Questions go to
144
+ [Discussions](https://github.com/tushar-mahalya/kdev/discussions). How to set
145
+ up, test without spending GPU quota, and send a pull request:
146
+ [CONTRIBUTING.md](https://github.com/tushar-mahalya/kdev/blob/main/CONTRIBUTING.md).
147
+
148
+ ## Security
149
+
150
+ Access is public-key SSH only. Kaggle has no API for notebook Secrets, so the
151
+ tunnel credentials sit in the private notebook's source, readable by anyone
152
+ with Can Edit. Kaggle allows one account per person and restricts tunnelling
153
+ out of notebooks; know the rules you are working under. Details are in
154
+ [Security and limits](https://kdev-cli.pages.dev/docs/security/). Report a
155
+ vulnerability privately, as
156
+ [SECURITY.md](https://github.com/tushar-mahalya/kdev/blob/main/SECURITY.md)
157
+ describes.
158
+
159
+ ## License
160
+
161
+ [MIT](https://github.com/tushar-mahalya/kdev/blob/main/LICENSE). kdev is an
162
+ independent project, not affiliated with Kaggle, Google or Cloudflare.
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "kdev-cli"
3
- version = "0.1.3"
3
+ version = "0.2.0"
4
4
  description = "A Kaggle notebook as your remote dev box: SSH and VS Code in, files that persist across sessions, accounts and machines."
5
5
  readme = "README.md"
6
6
  requires-python = ">=3.11"
@@ -28,11 +28,15 @@ dependencies = [
28
28
  "kaggle>=2.2,<3",
29
29
  "typer>=0.27,<1",
30
30
  "questionary>=2.0,<3",
31
+ # The home menu is a small prompt_toolkit app of its own (questionary is
32
+ # built on it too).
33
+ "prompt-toolkit>=3.0.36,<4",
31
34
  "rich>=13,<16",
32
35
  ]
33
36
 
34
37
  [project.urls]
35
- Homepage = "https://github.com/tushar-mahalya/kdev"
38
+ Homepage = "https://kdev-cli.pages.dev"
39
+ Documentation = "https://kdev-cli.pages.dev/docs/"
36
40
  Repository = "https://github.com/tushar-mahalya/kdev"
37
41
  Issues = "https://github.com/tushar-mahalya/kdev/issues"
38
42
  Changelog = "https://github.com/tushar-mahalya/kdev/blob/main/CHANGELOG.md"
@@ -55,7 +59,7 @@ include = ["src/kdev", "tests", "README.md", "LICENSE", "pyproject.toml"]
55
59
  [dependency-groups]
56
60
  # ruff is pinned to the version .pre-commit-config.yaml runs, so a clean
57
61
  # `uv run ruff` locally means a clean hook and a clean CI.
58
- dev = ["pytest>=8", "ruff==0.16.8", "pre-commit>=4"]
62
+ dev = ["pytest>=8", "pytest-cov>=7.1", "ruff==0.16.10", "pre-commit>=4", "basedpyright>=1.40"]
59
63
 
60
64
  [tool.pytest.ini_options]
61
65
  testpaths = ["tests"]
@@ -71,3 +75,12 @@ docstring-code-format = true
71
75
  [tool.ruff.lint]
72
76
  select = ["E", "F", "W", "I", "UP", "B", "SIM", "RUF"]
73
77
  ignore = ["E501", "RUF001", "RUF002", "RUF003"] # the design glyphs are deliberate
78
+
79
+ # Basic mode for now: catches wrong types, misspelled attributes and
80
+ # str | None passed where str is needed, without demanding full strictness.
81
+ # kdev_box.py runs inside the Kaggle notebook with only the standard
82
+ # library, so it must never gain imports from this package at runtime.
83
+ [tool.pyright]
84
+ include = ["src", "tests"]
85
+ pythonVersion = "3.11"
86
+ typeCheckingMode = "basic"