blob: b1a89d9050e9425f0fedc84240389038d3421978 (
plain) (
blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
|
# colabctl
A command-line client for [Google Colab](https://colab.research.google.com/) written in Go.
It lets you list, run, and interact with your notebooks from the terminal.
## Installation
```sh
go install git.onurgunduz.com/colabctl@latest
```
## Getting started
### 1. Create OAuth2 credentials
1. Go to <https://console.cloud.google.com/apis/credentials>.
2. Create an **OAuth 2.0 Client ID** of type **Desktop application**.
3. Enable the **Google Drive API** for your project.
4. Download or copy the **Client ID** and **Client Secret**.
5. Add yourself to the tests users if your app is sandboxed.
### 2. Authenticate
```sh
export COLAB_CLIENT_ID=your-client-id
export COLAB_CLIENT_SECRET=your-client-secret
colabctl auth login
```
A browser window opens for Google sign-in. After approval, the token is stored locally in `~/.config/colab/sessions.json`, so you will not need to sign in again until the refresh token expires.
Alternatively, pass credentials once:
```sh
colabctl auth login --client-id <id> --client-secret <secret>
```
## Usage
```sh
# List notebooks
colabctl list
# Run all cells in a notebook (get the ID from colabctl list)
colabctl run ID
# Interactive REPL
colabctl exec ID
# Run on T4 GPU
echo '!nvidia-smi' | colabctl exec ID --accelerator T4
# Copy files to/from the active runtime
colabctl cp :/content/model.pt ./model.pt # download
colabctl cp train.py :/content/train.py # upload
# A directory is not copied directly; archive it on the runtime first.
# colabctl exec <id> <<< '!tar czf /content/out.tgz -C /content/model .'
# colabctl cp :content/out.tgz ./out.tgz
# Manage sessions
colabctl sessions
colabctl stop ID
# Check auth status
colabctl auth status
# Log out
colabctl auth logout
```
### REPL multi-line input
End a line with `\` to continue on the next line:
```
>>> for i in range(3): \
... print(i)
0
1
2
```
## How it works
1. `auth` starts a temporary localhost server for code exchange during authorization. The received refresh token is persisted to your HOME folder and reused automatically.
2. `list` queries the Google Drive API v3 for files with MIME type `application/vnd.google.colaboratory`.
3. `run` / `exec` calls the Colab session API (`POST /api/sessions`) to start a runtime, then connects to the Jupyter kernel over WebSocket using the Jupyter wire protocol (v5) to send `execute_request` messages and stream back output.
4. `cp` uses the Jupyter Contents API (`/api/contents`) over the runtime proxy to download or upload a single file. Paths are relative to the Jupyter server root. Directories are not handled directly; archive them on the runtime (`tar`) and copy the archive.
## Examples
Run GPU benchmark:
```sh
$ cat examples/torch_gpu_benchmark.py | colabctl exec ID --accelerator T4
Device: Tesla T4
Torch : 2.11.0+cu128
4096x4096 matmul: 32.98 ms/iter, 4.2 TFLOP/s (fp32)
```
Generate an image from a text prompt using SD-Turbo:
```sh
cat examples/txt2img.py | colabctl exec ID --accelerator T4 -o examples
```

SD-Turbo is about 2.5 GB and loads only on the first call; because the kernel persists between `exec` calls, later prompts reuse the loaded pipeline and finish in a second or two.
|