aboutsummaryrefslogtreecommitdiff
path: root/README.md
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
```

![fluffy-creature](./examples/a_hyper_detailed_ultra_fluffy_fantasy_cr.png)

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.