aboutsummaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
authorOnur Gündüz <ogunduz@gmail.com>2026-06-28 06:16:07 +0200
committerOnur Gündüz <ogunduz@gmail.com>2026-06-28 06:16:07 +0200
commit9eacbb42f9a5931bf33d968f775fc806c46b11b0 (patch)
treebf9a34182b2db560023ba0deb060146bdbcc0d34 /README.md
parent4137fae6df4e77198b8ddd9d9647a1ee0c7c49d3 (diff)
downloadcolabctl-9eacbb42f9a5931bf33d968f775fc806c46b11b0.tar.gz
colabctl-9eacbb42f9a5931bf33d968f775fc806c46b11b0.zip
Init
Diffstat (limited to 'README.md')
-rw-r--r--README.md89
1 files changed, 89 insertions, 0 deletions
diff --git a/README.md b/README.md
index 3251cba..42312b2 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,90 @@
# colabctl
+
+A command-line client for Google Colab written in Go.
+
+It lets you list, run, and interact with your notebooks from the terminal.
+
+## Installation
+
+```sh
+go install github.com/tetsuo/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
+
+# 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.
+
+## License
+
+MIT