aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--README.md89
-rw-r--r--auth.go79
-rw-r--r--cp.go164
-rw-r--r--exec.go220
-rw-r--r--go.mod38
-rw-r--r--go.sum86
-rw-r--r--internal/auth/oauth.go163
-rw-r--r--internal/config/config.go79
-rw-r--r--internal/config/sessions.go126
-rw-r--r--internal/drive/drive.go116
-rw-r--r--internal/notebook/notebook.go106
-rw-r--r--list.go58
-rw-r--r--main.go51
-rw-r--r--output.go118
-rw-r--r--run.go102
-rw-r--r--sessions.go85
16 files changed, 1680 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
diff --git a/auth.go b/auth.go
new file mode 100644
index 0000000..fecd428
--- /dev/null
+++ b/auth.go
@@ -0,0 +1,79 @@
+package main
+
+import (
+ "fmt"
+ "os"
+
+ "github.com/spf13/cobra"
+
+ "github.com/tetsuo/colabctl/internal/auth"
+ "github.com/tetsuo/colabctl/internal/config"
+)
+
+var authCmd = &cobra.Command{
+ Use: "auth",
+ Short: "Manage authentication",
+}
+
+var loginCmd = &cobra.Command{
+ Use: "login",
+ Short: "Log in to Google and store credentials locally",
+ RunE: func(cmd *cobra.Command, _ []string) error {
+ id, _ := cmd.Flags().GetString("client-id")
+ secret, _ := cmd.Flags().GetString("client-secret")
+
+ if id != "" {
+ clientID = id
+ }
+ if secret != "" {
+ clientSecret = secret
+ }
+ requireCredentials()
+
+ if err := auth.Login(cmd.Context(), clientID, clientSecret); err != nil {
+ return err
+ }
+ fmt.Println("Authentication successful. Token saved.")
+ return nil
+ },
+}
+
+var logoutCmd = &cobra.Command{
+ Use: "logout",
+ Short: "Remove locally stored credentials",
+ RunE: func(_ *cobra.Command, _ []string) error {
+ if err := config.DeleteToken(); err != nil {
+ return err
+ }
+ fmt.Println("Logged out.")
+ return nil
+ },
+}
+
+var authStatusCmd = &cobra.Command{
+ Use: "status",
+ Short: "Show whether you are currently authenticated",
+ RunE: func(cmd *cobra.Command, _ []string) error {
+ tok, err := config.LoadToken()
+ if err != nil {
+ fmt.Fprintln(os.Stderr, "Not authenticated. Run `colabctl auth login`.")
+ return nil
+ }
+ if tok.Valid() {
+ fmt.Println("Authenticated. Token is valid.")
+ } else {
+ fmt.Println("Authenticated (token expired, will be refreshed automatically).")
+ }
+ return nil
+ },
+}
+
+func init() {
+ loginCmd.Flags().String("client-id", "", "Google OAuth2 client ID (overrides COLAB_CLIENT_ID)")
+ loginCmd.Flags().String("client-secret", "", "Google OAuth2 client secret (overrides COLAB_CLIENT_SECRET)")
+
+ authCmd.AddCommand(loginCmd)
+ authCmd.AddCommand(logoutCmd)
+ authCmd.AddCommand(authStatusCmd)
+ rootCmd.AddCommand(authCmd)
+}
diff --git a/cp.go b/cp.go
new file mode 100644
index 0000000..af1b418
--- /dev/null
+++ b/cp.go
@@ -0,0 +1,164 @@
+package main
+
+import (
+ "context"
+ "fmt"
+ "os"
+ "path"
+ "path/filepath"
+ "strings"
+
+ "github.com/spf13/cobra"
+
+ "github.com/tetsuo/colabctl/internal/auth"
+ "github.com/tetsuo/colabctl/internal/colab"
+)
+
+// remoteSpec is a parsed copy endpoint. When isRemote is true the location
+// lives on a runtime; endpoint may be empty to mean "the only active runtime".
+type remoteSpec struct {
+ isRemote bool
+ endpoint string
+ path string
+}
+
+// parseSpec splits an scp-style argument. An argument is treated as remote when
+// it contains a colon that comes before any slash, mirroring scp. The part
+// before the colon is the runtime endpoint, or empty for the active runtime.
+func parseSpec(arg string) remoteSpec {
+ idx := strings.IndexByte(arg, ':')
+ if idx < 0 || strings.IndexByte(arg[:idx], '/') >= 0 {
+ return remoteSpec{isRemote: false, path: arg}
+ }
+ return remoteSpec{isRemote: true, endpoint: arg[:idx], path: arg[idx+1:]}
+}
+
+var cpCmd = &cobra.Command{
+ Use: "cp <src> <dst>",
+ Short: "Copy files between your machine and a Colab runtime (scp-style)",
+ Long: `Copy a file to or from an active Colab runtime, using scp-style paths.
+
+A remote location is written as endpoint:path. Leave the endpoint empty to use
+the only active runtime:
+
+ # Download a trained model from the active runtime.
+ colabctl cp :/content/model.pt ./model.pt
+
+ # Upload a training script to a specific runtime.
+ colabctl cp train.py gpu-t4-s-abc123:/content/train.py
+
+Get the endpoint from 'colabctl sessions'. Directories are not copied directly;
+archive them on the runtime first (tar) and copy the archive.`,
+ Args: cobra.ExactArgs(2),
+ RunE: func(cmd *cobra.Command, args []string) error {
+ requireCredentials()
+ ctx := cmd.Context()
+
+ src := parseSpec(args[0])
+ dst := parseSpec(args[1])
+
+ if src.isRemote == dst.isRemote {
+ if src.isRemote {
+ return fmt.Errorf("copying between two runtimes is not supported")
+ }
+ return fmt.Errorf("at least one path must be remote (endpoint:path); use cp(1) for local copies")
+ }
+
+ httpClient, err := auth.Client(ctx, clientID, clientSecret)
+ if err != nil {
+ return err
+ }
+ client := colab.New(httpClient)
+
+ if src.isRemote {
+ return download(ctx, client, src, dst.path)
+ }
+ return upload(ctx, client, src.path, dst)
+ },
+}
+
+// resolveRuntime finds an active runtime. With an explicit endpoint it looks
+// that one up; otherwise it requires exactly one active runtime.
+func resolveRuntime(ctx context.Context, client *colab.Client, endpoint string) (*colab.AssignmentInfo, error) {
+ if endpoint != "" {
+ return client.AssignmentFromEndpoint(ctx, endpoint)
+ }
+
+ runtimes, err := client.ListAssignments(ctx)
+ if err != nil {
+ return nil, err
+ }
+ switch len(runtimes) {
+ case 0:
+ return nil, fmt.Errorf("no active runtimes: start one with 'colabctl exec', or name one as endpoint:path")
+ case 1:
+ return client.AssignmentFromEndpoint(ctx, runtimes[0].Endpoint)
+ default:
+ var b strings.Builder
+ fmt.Fprintf(&b, "%d active runtimes: name one in the path as endpoint:path:\n", len(runtimes))
+ for _, r := range runtimes {
+ fmt.Fprintf(&b, " %s\n", r.Endpoint)
+ }
+ return nil, fmt.Errorf("%s", b.String())
+ }
+}
+
+func download(ctx context.Context, client *colab.Client, src remoteSpec, localPath string) error {
+ assignment, err := resolveRuntime(ctx, client, src.endpoint)
+ if err != nil {
+ return err
+ }
+
+ fc, err := client.FetchFile(ctx, assignment, src.path)
+ if err != nil {
+ return err
+ }
+
+ // If the local target is a directory (or ends with a separator), keep the
+ // remote file name inside it.
+ target := localPath
+ if target == "" || strings.HasSuffix(target, string(os.PathSeparator)) {
+ target = filepath.Join(target, fc.Name)
+ } else if fi, statErr := os.Stat(target); statErr == nil && fi.IsDir() {
+ target = filepath.Join(target, fc.Name)
+ }
+
+ if dir := filepath.Dir(target); dir != "" {
+ if err := os.MkdirAll(dir, 0o755); err != nil {
+ return err
+ }
+ }
+ if err := os.WriteFile(target, fc.Data, 0o644); err != nil {
+ return err
+ }
+ fmt.Fprintf(os.Stderr, "Downloaded %s (%d bytes) -> %s\n", src.path, len(fc.Data), target)
+ return nil
+}
+
+func upload(ctx context.Context, client *colab.Client, localPath string, dst remoteSpec) error {
+ data, err := os.ReadFile(localPath)
+ if err != nil {
+ return err
+ }
+
+ assignment, err := resolveRuntime(ctx, client, dst.endpoint)
+ if err != nil {
+ return err
+ }
+
+ // If the remote target names a directory, keep the local file name.
+ remotePath := dst.path
+ if remotePath == "" || strings.HasSuffix(remotePath, "/") {
+ remotePath = path.Join(remotePath, filepath.Base(localPath))
+ }
+
+ if err := client.PutFile(ctx, assignment, remotePath, data); err != nil {
+ return err
+ }
+ fmt.Fprintf(os.Stderr, "Uploaded %s (%d bytes) -> %s\n", localPath, len(data), remotePath)
+ return nil
+}
+
+func init() {
+ rootCmd.AddCommand(cpCmd)
+}
diff --git a/exec.go b/exec.go
new file mode 100644
index 0000000..8287c41
--- /dev/null
+++ b/exec.go
@@ -0,0 +1,220 @@
+package main
+
+import (
+ "bufio"
+ "fmt"
+ "io"
+ "os"
+ "strings"
+ "time"
+
+ "github.com/spf13/cobra"
+
+ "github.com/tetsuo/colabctl/internal/auth"
+ "github.com/tetsuo/colabctl/internal/colab"
+ "github.com/tetsuo/colabctl/internal/config"
+)
+
+var execCmd = &cobra.Command{
+ Use: "exec <file-id>",
+ Short: "Open an interactive REPL connected to a Colab runtime",
+ Long: `Connects to a Colab runtime and opens an interactive REPL.
+
+By default a new runtime is allocated. If you already have a runtime running
+(see 'colabctl sessions'), pass its endpoint with --session to reuse it instead
+of allocating a new one. If only one runtime is active it is reused
+automatically.
+
+Get the file ID from:
+
+ colabctl list`,
+ Args: cobra.ExactArgs(1),
+ RunE: func(cmd *cobra.Command, args []string) error {
+ requireCredentials()
+
+ fileID := args[0]
+ ctx := cmd.Context()
+ sessionEndpoint, _ := cmd.Flags().GetString("session")
+ accelerator, _ := cmd.Flags().GetString("accelerator")
+ outputDir, _ := cmd.Flags().GetString("output-dir")
+
+ httpClient, err := auth.Client(ctx, clientID, clientSecret)
+ if err != nil {
+ return err
+ }
+
+ colabClient := colab.New(httpClient)
+
+ var assignment *colab.AssignmentInfo
+
+ // resolveFromCache tries the local session cache for the given endpoint.
+ // Returns nil (no error) when the cached entry is missing or expired.
+ resolveFromCache := func(endpoint string) *colab.AssignmentInfo {
+ s, err := config.LoadSession(endpoint)
+ if err != nil || s == nil || !s.Valid() {
+ return nil
+ }
+ fmt.Fprintf(os.Stderr, "Using cached session (endpoint %s, token valid until %s)\n\n",
+ s.Endpoint, s.TokenExpiresAt.Format("15:04:05"))
+ return &colab.AssignmentInfo{
+ Endpoint: s.Endpoint,
+ RuntimeProxyInfo: colab.RuntimeProxyInfo{
+ Token: s.Token,
+ URL: s.URL,
+ },
+ }
+ }
+
+ if sessionEndpoint != "" {
+ // User explicitly named an endpoint; check cache first.
+ if a := resolveFromCache(sessionEndpoint); a != nil {
+ assignment = a
+ } else {
+ assignment, err = colabClient.AssignmentFromEndpoint(ctx, sessionEndpoint)
+ if err != nil {
+ return fmt.Errorf("connect to session %s: %w", sessionEndpoint, err)
+ }
+ fmt.Fprintf(os.Stderr, "Connected to existing runtime (endpoint %s)\n\n", assignment.Endpoint)
+ }
+ } else {
+ // Check whether the user already has active runtimes.
+ runtimes, listErr := colabClient.ListAssignments(ctx)
+ if listErr == nil && len(runtimes) == 1 {
+ fmt.Fprintf(os.Stderr, "Reusing existing runtime (endpoint %s)\n", runtimes[0].Endpoint)
+ fmt.Fprintf(os.Stderr, " Tip: use --session <endpoint> to choose a specific one.\n\n")
+ if a := resolveFromCache(runtimes[0].Endpoint); a != nil {
+ assignment = a
+ } else {
+ assignment, err = colabClient.AssignmentFromEndpoint(ctx, runtimes[0].Endpoint)
+ if err != nil {
+ return fmt.Errorf("connect to existing runtime: %w", err)
+ }
+ }
+ } else if listErr == nil && len(runtimes) > 1 {
+ fmt.Fprintf(os.Stderr, "You have %d active runtimes. Use --session <endpoint> to pick one:\n\n", len(runtimes))
+ for _, r := range runtimes {
+ accel := r.Accelerator
+ if accel == "" {
+ accel = "CPU"
+ }
+ fmt.Fprintf(os.Stderr, " %s (%s)\n", r.Endpoint, accel)
+ }
+ fmt.Fprintln(os.Stderr)
+ return fmt.Errorf("specify a runtime with --session <endpoint>")
+ } else {
+ // No existing runtimes (or list failed); allocate a new one.
+ fmt.Fprintf(os.Stderr, "Starting Colab runtime for %s …\n", fileID)
+ assignment, err = colabClient.Assign(ctx, notebookHash(), "", accelerator)
+ if err != nil {
+ return fmt.Errorf("start runtime: %w", err)
+ }
+ fmt.Fprintf(os.Stderr, "Runtime ready (endpoint %s)\n\n", assignment.Endpoint)
+ }
+ }
+
+ // Persist the assignment so the next invocation skips the assign round-trip.
+ _ = config.SaveSession(&config.SessionState{
+ Endpoint: assignment.Endpoint,
+ URL: assignment.RuntimeProxyInfo.URL,
+ Token: assignment.RuntimeProxyInfo.Token,
+ TokenExpiresAt: time.Now().Add(time.Duration(assignment.RuntimeProxyInfo.TokenExpiresInSecs) * time.Second),
+ })
+
+ kernel, err := colab.CreateAndConnectKernel(ctx, assignment)
+ if err != nil {
+ return fmt.Errorf("connect to kernel: %w", err)
+ }
+ defer kernel.Close()
+
+ // Non-interactive mode: stdin is a pipe; read all input and execute once.
+ if fi, err := os.Stdin.Stat(); err == nil && fi.Mode()&os.ModeCharDevice == 0 {
+ input, err := io.ReadAll(os.Stdin)
+ if err != nil {
+ return fmt.Errorf("read stdin: %w", err)
+ }
+ code := strings.TrimRight(string(input), "\n")
+ if strings.TrimSpace(code) == "" {
+ return nil
+ }
+ outCh, err := kernel.Execute(ctx, code)
+ if err != nil {
+ return fmt.Errorf("execute: %w", err)
+ }
+ printOutputs(outCh, outputDir)
+ return nil
+ }
+
+ // Interactive REPL.
+ scanner := bufio.NewScanner(os.Stdin)
+ // Allow large pastes.
+ scanner.Buffer(make([]byte, 1024*1024), 1024*1024)
+
+ fmt.Println(`Colab REPL; connected to a live Colab kernel.
+Type Python code and press Enter to run a single line.
+To run a block: paste or type multiple lines, then press Enter twice on a blank line.
+Commands: :quit :exit :help`)
+
+ for {
+ fmt.Print(">>> ")
+ var lines []string
+ prevBlank := false
+ for {
+ if !scanner.Scan() {
+ fmt.Println()
+ return scanner.Err()
+ }
+ line := scanner.Text()
+
+ if len(lines) == 0 {
+ // First line: handle special commands.
+ switch line {
+ case ":quit", ":exit":
+ return nil
+ case ":help":
+ fmt.Println("Type Python code. Press Enter twice on a blank line to execute a block. :quit to exit.")
+ goto nextPrompt
+ case "":
+ // Blank first line; just show a new prompt.
+ goto nextPrompt
+ }
+ }
+
+ // Two consecutive blank lines end the block (same as IPython).
+ if line == "" && prevBlank {
+ // Drop the trailing blank lines from the block.
+ for len(lines) > 0 && lines[len(lines)-1] == "" {
+ lines = lines[:len(lines)-1]
+ }
+ break
+ }
+
+ prevBlank = line == ""
+ lines = append(lines, line)
+ }
+
+ {
+ code := strings.Join(lines, "\n")
+ code = strings.TrimRight(code, "\n")
+ if strings.TrimSpace(code) == "" {
+ goto nextPrompt
+ }
+
+ outCh, err := kernel.Execute(ctx, code)
+ if err != nil {
+ fmt.Fprintf(os.Stderr, "error: %v\n", err)
+ goto nextPrompt
+ }
+ printOutputs(outCh, outputDir)
+ }
+
+ nextPrompt:
+ }
+ },
+}
+
+func init() {
+ execCmd.Flags().StringP("session", "s", "", "Endpoint ID of an existing runtime to reuse (from 'colabctl sessions')")
+ execCmd.Flags().StringP("accelerator", "a", "", "Accelerator for a new runtime: T4, A100, TPU, L4, A100-80GB (default: CPU)")
+ execCmd.Flags().StringP("output-dir", "o", "", "Directory to save binary outputs (images, audio, video) into (default: current directory)")
+ rootCmd.AddCommand(execCmd)
+}
diff --git a/go.mod b/go.mod
new file mode 100644
index 0000000..e4a8b2a
--- /dev/null
+++ b/go.mod
@@ -0,0 +1,38 @@
+module github.com/tetsuo/colabctl
+
+go 1.25.8
+
+require (
+ github.com/gorilla/websocket v1.5.3
+ github.com/spf13/cobra v1.8.1
+ golang.org/x/oauth2 v0.36.0
+ google.golang.org/api v0.286.0
+)
+
+require (
+ cloud.google.com/go/auth v0.20.0 // indirect
+ cloud.google.com/go/auth/oauth2adapt v0.2.8 // indirect
+ cloud.google.com/go/compute/metadata v0.9.0 // indirect
+ github.com/cespare/xxhash/v2 v2.3.0 // indirect
+ github.com/felixge/httpsnoop v1.0.4 // indirect
+ github.com/go-logr/logr v1.4.3 // indirect
+ github.com/go-logr/stdr v1.2.2 // indirect
+ github.com/google/s2a-go v0.1.9 // indirect
+ github.com/google/uuid v1.6.0 // indirect
+ github.com/googleapis/enterprise-certificate-proxy v0.3.16 // indirect
+ github.com/googleapis/gax-go/v2 v2.22.0 // indirect
+ github.com/inconshreveable/mousetrap v1.1.0 // indirect
+ github.com/spf13/pflag v1.0.5 // indirect
+ go.opentelemetry.io/auto/sdk v1.2.1 // indirect
+ go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.67.0 // indirect
+ go.opentelemetry.io/otel v1.43.0 // indirect
+ go.opentelemetry.io/otel/metric v1.43.0 // indirect
+ go.opentelemetry.io/otel/trace v1.43.0 // indirect
+ golang.org/x/crypto v0.53.0 // indirect
+ golang.org/x/net v0.56.0 // indirect
+ golang.org/x/sys v0.46.0 // indirect
+ golang.org/x/text v0.38.0 // indirect
+ google.golang.org/genproto/googleapis/rpc v0.0.0-20260610212136-7ab31c22f7ad // indirect
+ google.golang.org/grpc v1.81.1 // indirect
+ google.golang.org/protobuf v1.36.11 // indirect
+)
diff --git a/go.sum b/go.sum
new file mode 100644
index 0000000..5404200
--- /dev/null
+++ b/go.sum
@@ -0,0 +1,86 @@
+cloud.google.com/go/auth v0.20.0 h1:kXTssoVb4azsVDoUiF8KvxAqrsQcQtB53DcSgta74CA=
+cloud.google.com/go/auth v0.20.0/go.mod h1:942/yi/itH1SsmpyrbnTMDgGfdy2BUqIKyd0cyYLc5Q=
+cloud.google.com/go/auth/oauth2adapt v0.2.8 h1:keo8NaayQZ6wimpNSmW5OPc283g65QNIiLpZnkHRbnc=
+cloud.google.com/go/auth/oauth2adapt v0.2.8/go.mod h1:XQ9y31RkqZCcwJWNSx2Xvric3RrU88hAYYbjDWYDL+c=
+cloud.google.com/go/compute/metadata v0.9.0 h1:pDUj4QMoPejqq20dK0Pg2N4yG9zIkYGdBtwLoEkH9Zs=
+cloud.google.com/go/compute/metadata v0.9.0/go.mod h1:E0bWwX5wTnLPedCKqk3pJmVgCBSM6qQI1yTBdEb3C10=
+github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
+github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
+github.com/cpuguy83/go-md2man/v2 v2.0.4/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/felixge/httpsnoop v1.0.4 h1:NFTV2Zj1bL4mc9sqWACXbQFVBBg2W3GPvqp8/ESS2Wg=
+github.com/felixge/httpsnoop v1.0.4/go.mod h1:m8KPJKqk1gH5J9DgRY2ASl2lWCfGKXixSwevea8zH2U=
+github.com/go-logr/logr v1.2.2/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A=
+github.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI=
+github.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
+github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag=
+github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE=
+github.com/golang/protobuf v1.5.4 h1:i7eJL8qZTpSEXOPTxNKhASYpMn+8e5Q6AdndVa1dWek=
+github.com/golang/protobuf v1.5.4/go.mod h1:lnTiLA8Wa4RWRcIUkrtSVa5nRhsEGBg48fD6rSs7xps=
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
+github.com/google/s2a-go v0.1.9 h1:LGD7gtMgezd8a/Xak7mEWL0PjoTQFvpRudN895yqKW0=
+github.com/google/s2a-go v0.1.9/go.mod h1:YA0Ei2ZQL3acow2O62kdp9UlnvMmU7kA6Eutn0dXayM=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/googleapis/enterprise-certificate-proxy v0.3.16 h1:F/VPrx0YPBdksZJQdCAp0WUsqnNmZpUZszzfYt0M5Dw=
+github.com/googleapis/enterprise-certificate-proxy v0.3.16/go.mod h1:9Yb0eAkH/Xqhvv3zbeKf/+wMJqCeocWc6KIhDvEAuYE=
+github.com/googleapis/gax-go/v2 v2.22.0 h1:PjIWBpgGIVKGoCXuiCoP64altEJCj3/Ei+kSU5vlZD4=
+github.com/googleapis/gax-go/v2 v2.22.0/go.mod h1:irWBbALSr0Sk3qlqb9SyJ1h68WjgeFuiOzI4Rqw5+aY=
+github.com/gorilla/websocket v1.5.3 h1:saDtZ6Pbx/0u+bgYQ3q96pZgCzfhKXGPqt7kZ72aNNg=
+github.com/gorilla/websocket v1.5.3/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
+github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
+github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
+github.com/spf13/cobra v1.8.1 h1:e5/vxKd/rZsfSJMUX1agtjeTDf+qv1/JdBF8gg5k9ZM=
+github.com/spf13/cobra v1.8.1/go.mod h1:wHxEcudfqmLYa8iTfL+OuZPbBZkmvliBWKIezN3kD9Y=
+github.com/spf13/pflag v1.0.5 h1:iy+VFUOCP1a+8yFto/drg2CJ5u0yRoB7fZw3DKv/JXA=
+github.com/spf13/pflag v1.0.5/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64=
+go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y=
+go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.67.0 h1:OyrsyzuttWTSur2qN/Lm0m2a8yqyIjUVBZcxFPuXq2o=
+go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.67.0/go.mod h1:C2NGBr+kAB4bk3xtMXfZ94gqFDtg/GkI7e9zqGh5Beg=
+go.opentelemetry.io/otel v1.43.0 h1:mYIM03dnh5zfN7HautFE4ieIig9amkNANT+xcVxAj9I=
+go.opentelemetry.io/otel v1.43.0/go.mod h1:JuG+u74mvjvcm8vj8pI5XiHy1zDeoCS2LB1spIq7Ay0=
+go.opentelemetry.io/otel/metric v1.43.0 h1:d7638QeInOnuwOONPp4JAOGfbCEpYb+K6DVWvdxGzgM=
+go.opentelemetry.io/otel/metric v1.43.0/go.mod h1:RDnPtIxvqlgO8GRW18W6Z/4P462ldprJtfxHxyKd2PY=
+go.opentelemetry.io/otel/sdk v1.43.0 h1:pi5mE86i5rTeLXqoF/hhiBtUNcrAGHLKQdhg4h4V9Dg=
+go.opentelemetry.io/otel/sdk v1.43.0/go.mod h1:P+IkVU3iWukmiit/Yf9AWvpyRDlUeBaRg6Y+C58QHzg=
+go.opentelemetry.io/otel/sdk/metric v1.43.0 h1:S88dyqXjJkuBNLeMcVPRFXpRw2fuwdvfCGLEo89fDkw=
+go.opentelemetry.io/otel/sdk/metric v1.43.0/go.mod h1:C/RJtwSEJ5hzTiUz5pXF1kILHStzb9zFlIEe85bhj6A=
+go.opentelemetry.io/otel/trace v1.43.0 h1:BkNrHpup+4k4w+ZZ86CZoHHEkohws8AY+WTX09nk+3A=
+go.opentelemetry.io/otel/trace v1.43.0/go.mod h1:/QJhyVBUUswCphDVxq+8mld+AvhXZLhe+8WVFxiFff0=
+golang.org/x/crypto v0.53.0 h1:QZ4Muo8THX6CizN2vPPd5fBGHyogrdK9fG4wLPFUsto=
+golang.org/x/crypto v0.53.0/go.mod h1:DNLU434OwVakk9PzuwV8w62mAJpRJL3vsgcfp4Qnsio=
+golang.org/x/net v0.56.0 h1:Rw8j/hFzGvJUZwNBXnAtf5sVDVt+65SK2C7IxCxZt5o=
+golang.org/x/net v0.56.0/go.mod h1:D3Ku6r+V6JROoZK144D2XfMHFcMq/0zSfLelVTCFKec=
+golang.org/x/oauth2 v0.36.0 h1:peZ/1z27fi9hUOFCAZaHyrpWG5lwe0RJEEEeH0ThlIs=
+golang.org/x/oauth2 v0.36.0/go.mod h1:YDBUJMTkDnJS+A4BP4eZBjCqtokkg1hODuPjwiGPO7Q=
+golang.org/x/sync v0.21.0 h1:HLII4xRRTtCRkxYp4HNFF0Js/Og6q2i++KXbg0gHCwM=
+golang.org/x/sync v0.21.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
+golang.org/x/sys v0.46.0 h1:noSf2Fq6F8DBgS+LysIkx7rIExoNHJsxOAtPp4rthXw=
+golang.org/x/sys v0.46.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/text v0.38.0 h1:sXmwo9DwP3OK9EZ7PqAdaooSGozfl/3a6/xJcbzPRhE=
+golang.org/x/text v0.38.0/go.mod h1:YXZt3QhHUKYT53r2lLKFIVi6Ao1jdzrTR/KQ09qyxF4=
+gonum.org/v1/gonum v0.17.0 h1:VbpOemQlsSMrYmn7T2OUvQ4dqxQXU+ouZFQsZOx50z4=
+gonum.org/v1/gonum v0.17.0/go.mod h1:El3tOrEuMpv2UdMrbNlKEh9vd86bmQ6vqIcDwxEOc1E=
+google.golang.org/api v0.286.0 h1:TdTXMvzYKnWV1/lPbCdbXRqBrkDqjPto22H2xeZZ8LI=
+google.golang.org/api v0.286.0/go.mod h1:NlOlUIr8MPoIhT9Bb/oUnRuHbJOLwxb6JSYJM8Yz+jQ=
+google.golang.org/genproto v0.0.0-20260319201613-d00831a3d3e7 h1:XzmzkmB14QhVhgnawEVsOn6OFsnpyxNPRY9QV01dNB0=
+google.golang.org/genproto v0.0.0-20260319201613-d00831a3d3e7/go.mod h1:L43LFes82YgSonw6iTXTxXUX1OlULt4AQtkik4ULL/I=
+google.golang.org/genproto/googleapis/api v0.0.0-20260319201613-d00831a3d3e7 h1:41r6JMbpzBMen0R/4TZeeAmGXSJC7DftGINUodzTkPI=
+google.golang.org/genproto/googleapis/api v0.0.0-20260319201613-d00831a3d3e7/go.mod h1:EIQZ5bFCfRQDV4MhRle7+OgjNtZ6P1PiZBgAKuxXu/Y=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20260610212136-7ab31c22f7ad h1:45WmJvIV6C2+O/jjLkPUH+F3aOj/1miDoU2DD0+NWbg=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20260610212136-7ab31c22f7ad/go.mod h1:4Hqkh8ycfw05ld/3BWL7rJOSfebL2Q+DVDeRgYgxUU8=
+google.golang.org/grpc v1.81.1 h1:VnnIIZ88UzOOKLukQi+ImGz8O1Wdp8nAGGnvOfEIWQQ=
+google.golang.org/grpc v1.81.1/go.mod h1:xGH9GfzOyMTGIOXBJmXt+BX/V0kcdQbdcuwQ/zNw42I=
+google.golang.org/protobuf v1.36.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBNVE=
+google.golang.org/protobuf v1.36.11/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
diff --git a/internal/auth/oauth.go b/internal/auth/oauth.go
new file mode 100644
index 0000000..177bbdd
--- /dev/null
+++ b/internal/auth/oauth.go
@@ -0,0 +1,163 @@
+// Package auth handles Google OAuth2 for the CLI using a local loopback server
+// to receive the authorization code.
+package auth
+
+import (
+ "context"
+ "crypto/rand"
+ "encoding/base64"
+ "errors"
+ "fmt"
+ "net"
+ "net/http"
+ "os/exec"
+ "runtime"
+ "time"
+
+ "golang.org/x/oauth2"
+ "golang.org/x/oauth2/google"
+
+ "github.com/tetsuo/colabctl/internal/config"
+)
+
+// Scopes required to use the Drive API and the Colab runtime API.
+// The colaboratory scope is mandatory; without it the /tun/m/assign
+// endpoint returns 403 SCOPE_NOT_PERMITTED.
+var scopes = []string{
+ "openid",
+ "https://www.googleapis.com/auth/userinfo.profile",
+ "https://www.googleapis.com/auth/userinfo.email",
+ "https://www.googleapis.com/auth/cloud-platform",
+ "https://www.googleapis.com/auth/colaboratory",
+ "https://www.googleapis.com/auth/drive",
+}
+
+// oauthConfig builds an oauth2.Config from the supplied client credentials.
+func oauthConfig(clientID, clientSecret, redirectURL string) *oauth2.Config {
+ return &oauth2.Config{
+ ClientID: clientID,
+ ClientSecret: clientSecret,
+ RedirectURL: redirectURL,
+ Scopes: scopes,
+ Endpoint: google.Endpoint,
+ }
+}
+
+// Login performs an interactive OAuth2 flow. It starts a temporary local HTTP
+// server on a free port, opens the browser for the user, waits for the
+// authorization code, exchanges it for tokens, and persists them to disk.
+func Login(ctx context.Context, clientID, clientSecret string) error {
+ // Pick a free port on localhost.
+ listener, err := net.Listen("tcp", "127.0.0.1:0")
+ if err != nil {
+ return fmt.Errorf("start local server: %w", err)
+ }
+ port := listener.Addr().(*net.TCPAddr).Port
+ redirectURL := fmt.Sprintf("http://127.0.0.1:%d/callback", port)
+
+ cfg := oauthConfig(clientID, clientSecret, redirectURL)
+
+ // Generate a random state value to guard against CSRF.
+ state, err := randomState()
+ if err != nil {
+ return err
+ }
+
+ authURL := cfg.AuthCodeURL(state, oauth2.AccessTypeOffline, oauth2.ApprovalForce)
+
+ codeCh := make(chan string, 1)
+ errCh := make(chan error, 1)
+
+ mux := http.NewServeMux()
+ srv := &http.Server{Handler: mux}
+
+ mux.HandleFunc("/callback", func(w http.ResponseWriter, r *http.Request) {
+ if r.URL.Query().Get("state") != state {
+ http.Error(w, "state mismatch", http.StatusBadRequest)
+ errCh <- errors.New("oauth2 state mismatch; possible CSRF")
+ return
+ }
+ code := r.URL.Query().Get("code")
+ if code == "" {
+ msg := r.URL.Query().Get("error")
+ http.Error(w, "authorization denied", http.StatusBadRequest)
+ errCh <- fmt.Errorf("authorization denied: %s", msg)
+ return
+ }
+ fmt.Fprintln(w, "<html><body><h2>Authentication successful; you can close this tab.</h2></body></html>")
+ codeCh <- code
+ })
+
+ go func() {
+ if err := srv.Serve(listener); err != nil && !errors.Is(err, http.ErrServerClosed) {
+ errCh <- err
+ }
+ }()
+
+ fmt.Printf("Opening browser for authentication.\nIf the browser does not open, visit:\n\n %s\n\n", authURL)
+ openBrowser(authURL)
+
+ var code string
+ select {
+ case code = <-codeCh:
+ case err = <-errCh:
+ _ = srv.Shutdown(context.Background())
+ return err
+ case <-time.After(5 * time.Minute):
+ _ = srv.Shutdown(context.Background())
+ return errors.New("timed out waiting for authorization")
+ }
+ _ = srv.Shutdown(context.Background())
+
+ tok, err := cfg.Exchange(ctx, code)
+ if err != nil {
+ return fmt.Errorf("exchange code: %w", err)
+ }
+ return config.SaveToken(tok)
+}
+
+// TokenSource loads the stored token and wraps it in an auto-refreshing
+// TokenSource. Returns an error if no token has been saved (i.e. the user has
+// not yet run auth login).
+func TokenSource(ctx context.Context, clientID, clientSecret string) (oauth2.TokenSource, error) {
+ tok, err := config.LoadToken()
+ if err != nil {
+ return nil, fmt.Errorf("not authenticated; run \"colabctl auth login\" first: %w", err)
+ }
+ cfg := oauthConfig(clientID, clientSecret, "")
+ return cfg.TokenSource(ctx, tok), nil
+}
+
+// Client returns an *http.Client backed by the stored token.
+func Client(ctx context.Context, clientID, clientSecret string) (*http.Client, error) {
+ ts, err := TokenSource(ctx, clientID, clientSecret)
+ if err != nil {
+ return nil, err
+ }
+ return oauth2.NewClient(ctx, ts), nil
+}
+
+func randomState() (string, error) {
+ b := make([]byte, 16)
+ if _, err := rand.Read(b); err != nil {
+ return "", fmt.Errorf("generate state: %w", err)
+ }
+ return base64.URLEncoding.EncodeToString(b), nil
+}
+
+func openBrowser(url string) {
+ var cmd string
+ var args []string
+ switch runtime.GOOS {
+ case "darwin":
+ cmd = "open"
+ args = []string{url}
+ case "windows":
+ cmd = "rundll32"
+ args = []string{"url.dll,FileProtocolHandler", url}
+ default:
+ cmd = "xdg-open"
+ args = []string{url}
+ }
+ _ = exec.Command(cmd, args...).Start()
+}
diff --git a/internal/config/config.go b/internal/config/config.go
new file mode 100644
index 0000000..a850386
--- /dev/null
+++ b/internal/config/config.go
@@ -0,0 +1,79 @@
+package config
+
+import (
+ "encoding/json"
+ "errors"
+ "os"
+ "path/filepath"
+
+ "golang.org/x/oauth2"
+)
+
+// Dir returns the directory used to store all persistent state.
+func Dir() (string, error) {
+ home, err := os.UserHomeDir()
+ if err != nil {
+ return "", err
+ }
+ return filepath.Join(home, ".config", "colab"), nil
+}
+
+// TokenPath returns the path to the stored OAuth2 token file.
+func TokenPath() (string, error) {
+ dir, err := Dir()
+ if err != nil {
+ return "", err
+ }
+ return filepath.Join(dir, "token.json"), nil
+}
+
+// LoadToken reads the stored token from disk. Returns an error wrapping
+// os.ErrNotExist when no token has been saved yet.
+func LoadToken() (*oauth2.Token, error) {
+ path, err := TokenPath()
+ if err != nil {
+ return nil, err
+ }
+ f, err := os.Open(path)
+ if err != nil {
+ return nil, err
+ }
+ defer f.Close()
+
+ var tok oauth2.Token
+ if err := json.NewDecoder(f).Decode(&tok); err != nil {
+ return nil, err
+ }
+ return &tok, nil
+}
+
+// SaveToken writes the token to disk, creating parent directories as needed.
+func SaveToken(tok *oauth2.Token) error {
+ dir, err := Dir()
+ if err != nil {
+ return err
+ }
+ if err := os.MkdirAll(dir, 0700); err != nil {
+ return err
+ }
+ path := filepath.Join(dir, "token.json")
+ f, err := os.OpenFile(path, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, 0600)
+ if err != nil {
+ return err
+ }
+ defer f.Close()
+ return json.NewEncoder(f).Encode(tok)
+}
+
+// DeleteToken removes the stored token, effectively logging out.
+func DeleteToken() error {
+ path, err := TokenPath()
+ if err != nil {
+ return err
+ }
+ err = os.Remove(path)
+ if errors.Is(err, os.ErrNotExist) {
+ return nil
+ }
+ return err
+}
diff --git a/internal/config/sessions.go b/internal/config/sessions.go
new file mode 100644
index 0000000..cbc9ffa
--- /dev/null
+++ b/internal/config/sessions.go
@@ -0,0 +1,126 @@
+package config
+
+import (
+ "encoding/json"
+ "errors"
+ "os"
+ "path/filepath"
+ "time"
+)
+
+// SessionState is the on-disk record for one active Colab runtime.
+type SessionState struct {
+ Endpoint string `json:"endpoint"`
+ URL string `json:"url"`
+ Token string `json:"token"`
+ TokenExpiresAt time.Time `json:"tokenExpiresAt"`
+ KernelID string `json:"kernelId,omitempty"`
+}
+
+// Valid returns true if the session's proxy token has not yet expired.
+func (s *SessionState) Valid() bool {
+ return s.Token != "" && time.Now().Before(s.TokenExpiresAt)
+}
+
+type sessionFile struct {
+ Sessions map[string]*SessionState `json:"sessions"`
+}
+
+func sessionsPath() (string, error) {
+ dir, err := Dir()
+ if err != nil {
+ return "", err
+ }
+ return filepath.Join(dir, "sessions.json"), nil
+}
+
+func loadSessionFile() (*sessionFile, error) {
+ path, err := sessionsPath()
+ if err != nil {
+ return nil, err
+ }
+ f, err := os.Open(path)
+ if errors.Is(err, os.ErrNotExist) {
+ return &sessionFile{Sessions: map[string]*SessionState{}}, nil
+ }
+ if err != nil {
+ return nil, err
+ }
+ defer f.Close()
+
+ var sf sessionFile
+ if err := json.NewDecoder(f).Decode(&sf); err != nil {
+ return &sessionFile{Sessions: map[string]*SessionState{}}, nil
+ }
+ if sf.Sessions == nil {
+ sf.Sessions = map[string]*SessionState{}
+ }
+ return &sf, nil
+}
+
+func saveSessionFile(sf *sessionFile) error {
+ dir, err := Dir()
+ if err != nil {
+ return err
+ }
+ if err := os.MkdirAll(dir, 0700); err != nil {
+ return err
+ }
+ path, err := sessionsPath()
+ if err != nil {
+ return err
+ }
+ f, err := os.OpenFile(path, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, 0600)
+ if err != nil {
+ return err
+ }
+ defer f.Close()
+ return json.NewEncoder(f).Encode(sf)
+}
+
+// SaveSession persists a session under the given endpoint key.
+func SaveSession(s *SessionState) error {
+ sf, err := loadSessionFile()
+ if err != nil {
+ return err
+ }
+ sf.Sessions[s.Endpoint] = s
+ return saveSessionFile(sf)
+}
+
+// LoadSession returns the saved session for the given endpoint, or nil if not
+// found or the token has expired.
+func LoadSession(endpoint string) (*SessionState, error) {
+ sf, err := loadSessionFile()
+ if err != nil {
+ return nil, err
+ }
+ s, ok := sf.Sessions[endpoint]
+ if !ok {
+ return nil, nil
+ }
+ return s, nil
+}
+
+// ListSessions returns all saved sessions regardless of token validity.
+func ListSessions() ([]*SessionState, error) {
+ sf, err := loadSessionFile()
+ if err != nil {
+ return nil, err
+ }
+ out := make([]*SessionState, 0, len(sf.Sessions))
+ for _, s := range sf.Sessions {
+ out = append(out, s)
+ }
+ return out, nil
+}
+
+// DeleteSession removes a saved session by endpoint.
+func DeleteSession(endpoint string) error {
+ sf, err := loadSessionFile()
+ if err != nil {
+ return err
+ }
+ delete(sf.Sessions, endpoint)
+ return saveSessionFile(sf)
+}
diff --git a/internal/drive/drive.go b/internal/drive/drive.go
new file mode 100644
index 0000000..677880b
--- /dev/null
+++ b/internal/drive/drive.go
@@ -0,0 +1,116 @@
+// Package drive provides a thin wrapper around the Google Drive API v3 for
+// operations relevant to Colab notebooks.
+package drive
+
+import (
+ "context"
+ "fmt"
+ "net/http"
+
+ gdrive "google.golang.org/api/drive/v3"
+ "google.golang.org/api/googleapi"
+ "google.golang.org/api/option"
+)
+
+const colabMIMEType = "application/vnd.google.colaboratory"
+
+// Notebook is a minimal representation of a Colab notebook file in Drive.
+type Notebook struct {
+ ID string
+ Name string
+ Modified string // RFC 3339 string
+ URL string
+}
+
+// Client wraps the Drive API service.
+type Client struct {
+ svc *gdrive.Service
+}
+
+// New creates a Drive client using the provided authenticated HTTP client.
+func New(ctx context.Context, httpClient *http.Client) (*Client, error) {
+ svc, err := gdrive.NewService(ctx, option.WithHTTPClient(httpClient))
+ if err != nil {
+ return nil, fmt.Errorf("create drive service: %w", err)
+ }
+ return &Client{svc: svc}, nil
+}
+
+// ListNotebooks returns all Colab notebooks (.ipynb files with the Colab MIME
+// type) that are owned by or shared with the authenticated user.
+func (c *Client) ListNotebooks(ctx context.Context) ([]*Notebook, error) {
+ var notebooks []*Notebook
+ pageToken := ""
+ fields := googleapi.Field("nextPageToken, files(id, name, modifiedTime, webViewLink)")
+ query := fmt.Sprintf("mimeType='%s' and trashed=false", colabMIMEType)
+
+ for {
+ call := c.svc.Files.List().
+ Q(query).
+ Fields(fields).
+ OrderBy("modifiedTime desc").
+ PageSize(100).
+ Context(ctx)
+ if pageToken != "" {
+ call = call.PageToken(pageToken)
+ }
+
+ resp, err := call.Do()
+ if err != nil {
+ return nil, fmt.Errorf("list drive files: %w", err)
+ }
+ for _, f := range resp.Files {
+ notebooks = append(notebooks, &Notebook{
+ ID: f.Id,
+ Name: f.Name,
+ Modified: f.ModifiedTime,
+ URL: f.WebViewLink,
+ })
+ }
+ if resp.NextPageToken == "" {
+ break
+ }
+ pageToken = resp.NextPageToken
+ }
+ return notebooks, nil
+}
+
+// GetNotebook fetches the raw JSON bytes of a notebook from Drive by its file
+// ID. The content is the raw .ipynb JSON.
+func (c *Client) GetNotebook(ctx context.Context, fileID string) ([]byte, error) {
+ resp, err := c.svc.Files.Export(fileID, "application/json").Context(ctx).Download()
+ if err != nil {
+ // Colab files are not Google Docs, so Export will not work.
+ // Use the plain media download instead.
+ resp2, err2 := c.svc.Files.Get(fileID).Context(ctx).Download()
+ if err2 != nil {
+ return nil, fmt.Errorf("download notebook (file %s): %w", fileID, err)
+ }
+ defer resp2.Body.Close()
+ buf := make([]byte, 0, 512*1024)
+ tmp := make([]byte, 32*1024)
+ for {
+ n, readErr := resp2.Body.Read(tmp)
+ if n > 0 {
+ buf = append(buf, tmp[:n]...)
+ }
+ if readErr != nil {
+ break
+ }
+ }
+ return buf, nil
+ }
+ defer resp.Body.Close()
+ buf := make([]byte, 0, 512*1024)
+ tmp := make([]byte, 32*1024)
+ for {
+ n, readErr := resp.Body.Read(tmp)
+ if n > 0 {
+ buf = append(buf, tmp[:n]...)
+ }
+ if readErr != nil {
+ break
+ }
+ }
+ return buf, nil
+}
diff --git a/internal/notebook/notebook.go b/internal/notebook/notebook.go
new file mode 100644
index 0000000..9881154
--- /dev/null
+++ b/internal/notebook/notebook.go
@@ -0,0 +1,106 @@
+// Package notebook parses and represents Jupyter/Colab .ipynb files.
+package notebook
+
+import (
+ "encoding/json"
+ "fmt"
+)
+
+// Cell types used in notebooks.
+const (
+ CellTypeCode = "code"
+ CellTypeMarkdown = "markdown"
+ CellTypeRaw = "raw"
+)
+
+// Source is a notebook cell's source, which can be stored as a single string
+// or a list of strings (lines) in the JSON format.
+type Source []string
+
+func (s *Source) UnmarshalJSON(data []byte) error {
+ // Try string first.
+ var str string
+ if err := json.Unmarshal(data, &str); err == nil {
+ *s = Source{str}
+ return nil
+ }
+ // Fall back to slice.
+ var lines []string
+ if err := json.Unmarshal(data, &lines); err != nil {
+ return err
+ }
+ *s = Source(lines)
+ return nil
+}
+
+// String joins all source lines into one string.
+func (s Source) String() string {
+ out := ""
+ for _, l := range s {
+ out += l
+ }
+ return out
+}
+
+// Output represents one output entry produced by a cell execution.
+type Output struct {
+ OutputType string `json:"output_type"`
+ Text Source `json:"text"`
+ Data json.RawMessage `json:"data"`
+ EValue Source `json:"evalue"`
+ Traceback []string `json:"traceback"`
+}
+
+// Cell is a single cell in the notebook.
+type Cell struct {
+ CellType string `json:"cell_type"`
+ ID string `json:"id"`
+ Source Source `json:"source"`
+ Outputs []Output `json:"outputs"`
+ Metadata struct {
+ ExecutionCount *int `json:"execution_count"`
+ } `json:"metadata"`
+}
+
+// Notebook is the top-level structure of a .ipynb file.
+type Notebook struct {
+ NBFormat int `json:"nbformat"`
+ NBFormatMinor int `json:"nbformat_minor"`
+ Metadata struct {
+ KernelInfo struct {
+ Name string `json:"name"`
+ } `json:"kernelspec"`
+ LanguageInfo struct {
+ Name string `json:"name"`
+ } `json:"language_info"`
+ CoLab struct {
+ Name string `json:"name"`
+ } `json:"colab"`
+ } `json:"metadata"`
+ Cells []*Cell `json:"cells"`
+}
+
+// Parse decodes a .ipynb JSON payload into a Notebook.
+func Parse(data []byte) (*Notebook, error) {
+ var nb Notebook
+ if err := json.Unmarshal(data, &nb); err != nil {
+ return nil, fmt.Errorf("parse notebook: %w", err)
+ }
+ return &nb, nil
+}
+
+// CodeCells returns only the code cells in order.
+func (nb *Notebook) CodeCells() []*Cell {
+ var out []*Cell
+ for _, c := range nb.Cells {
+ if c.CellType == CellTypeCode {
+ out = append(out, c)
+ }
+ }
+ return out
+}
+
+// Title returns the notebook name from metadata if available.
+func (nb *Notebook) Title() string {
+ return nb.Metadata.CoLab.Name
+}
diff --git a/list.go b/list.go
new file mode 100644
index 0000000..904cc29
--- /dev/null
+++ b/list.go
@@ -0,0 +1,58 @@
+package main
+
+import (
+ "fmt"
+ "os"
+ "text/tabwriter"
+ "time"
+
+ "github.com/spf13/cobra"
+
+ "github.com/tetsuo/colabctl/internal/auth"
+ "github.com/tetsuo/colabctl/internal/drive"
+)
+
+var listCmd = &cobra.Command{
+ Use: "list",
+ Aliases: []string{"ls"},
+ Short: "List Colab notebooks from Google Drive",
+ RunE: func(cmd *cobra.Command, _ []string) error {
+ requireCredentials()
+
+ httpClient, err := auth.Client(cmd.Context(), clientID, clientSecret)
+ if err != nil {
+ return err
+ }
+
+ driveClient, err := drive.New(cmd.Context(), httpClient)
+ if err != nil {
+ return err
+ }
+
+ notebooks, err := driveClient.ListNotebooks(cmd.Context())
+ if err != nil {
+ return err
+ }
+
+ if len(notebooks) == 0 {
+ fmt.Println("No Colab notebooks found in your Drive.")
+ return nil
+ }
+
+ w := tabwriter.NewWriter(os.Stdout, 0, 0, 2, ' ', 0)
+ fmt.Fprintln(w, "ID\tNAME\tMODIFIED")
+ fmt.Fprintln(w, "--\t----\t--------")
+ for _, nb := range notebooks {
+ modified := nb.Modified
+ if t, err := time.Parse(time.RFC3339, nb.Modified); err == nil {
+ modified = t.Format("2006-01-02 15:04")
+ }
+ fmt.Fprintf(w, "%s\t%s\t%s\n", nb.ID, nb.Name, modified)
+ }
+ return w.Flush()
+ },
+}
+
+func init() {
+ rootCmd.AddCommand(listCmd)
+}
diff --git a/main.go b/main.go
new file mode 100644
index 0000000..512f5f0
--- /dev/null
+++ b/main.go
@@ -0,0 +1,51 @@
+package main
+
+import (
+ "fmt"
+ "os"
+
+ "github.com/spf13/cobra"
+)
+
+var (
+ clientID = ""
+ clientSecret = ""
+)
+
+var rootCmd = &cobra.Command{
+ Use: "colabctl",
+}
+
+func main() {
+ if err := rootCmd.Execute(); err != nil {
+ fmt.Fprintln(os.Stderr, err)
+ os.Exit(1)
+ }
+}
+
+func init() {
+ // Allow credentials to be provided via environment variables as a
+ // convenient alternative to build-time injection.
+ if id := os.Getenv("COLAB_CLIENT_ID"); id != "" {
+ clientID = id
+ }
+ if secret := os.Getenv("COLAB_CLIENT_SECRET"); secret != "" {
+ clientSecret = secret
+ }
+}
+
+// requireCredentials prints a helpful error and exits if the OAuth2 client
+// credentials have not been configured.
+func requireCredentials() {
+ if clientID == "" || clientSecret == "" {
+ fmt.Fprintln(os.Stderr, `Error: OAuth2 credentials not set.
+
+Set COLAB_CLIENT_ID and COLAB_CLIENT_SECRET environment variables, or run:
+
+ colabctl auth login --client-id <id> --client-secret <secret>
+
+To create credentials, visit:
+ https://console.cloud.google.com/apis/credentials`)
+ os.Exit(1)
+ }
+}
diff --git a/output.go b/output.go
new file mode 100644
index 0000000..1fb405f
--- /dev/null
+++ b/output.go
@@ -0,0 +1,118 @@
+package main
+
+import (
+ "crypto/rand"
+ "encoding/hex"
+ "fmt"
+ "os"
+ "path/filepath"
+ "strings"
+
+ "github.com/tetsuo/colabctl/internal/colab"
+)
+
+// mimeExtensions maps MIME types to file extensions for binary outputs.
+var mimeExtensions = map[string]string{
+ "image/png": ".png",
+ "image/jpeg": ".jpg",
+ "image/gif": ".gif",
+ "image/svg+xml": ".svg",
+ "audio/wav": ".wav",
+ "audio/mpeg": ".mp3",
+ "audio/mp3": ".mp3",
+ "audio/ogg": ".ogg",
+ "video/mp4": ".mp4",
+ "video/webm": ".webm",
+}
+
+// mimeOrder controls which MIME type is saved when a message carries several
+// (prefer the highest-quality representation).
+var mimeOrder = []string{
+ "image/png", "image/jpeg", "image/gif", "image/svg+xml",
+ "audio/wav", "audio/mpeg", "audio/mp3", "audio/ogg",
+ "video/mp4", "video/webm",
+}
+
+// printOutputs drains the channel of kernel outputs and writes them to the
+// terminal. stdout/result go to os.Stdout; errors/stderr go to os.Stderr.
+// Binary outputs (images, audio, video) are saved to files. They go in
+// outputDir when it is set, otherwise the current directory. The function
+// blocks until the channel is closed.
+func printOutputs(ch <-chan colab.KernelOutput, outputDir string) {
+ fileCount := 0
+ for out := range ch {
+ // One displayed object can arrive in several encodings (a figure as
+ // both PNG and JPEG, for example). Save only the highest-priority one
+ // so each object yields a single file.
+ for _, mime := range mimeOrder {
+ data, ok := out.BinaryData[mime]
+ if !ok {
+ continue
+ }
+ ext := mimeExtensions[mime]
+ fileCount++
+ // Prefer a name the cell supplied via display metadata; otherwise
+ // fall back to a numbered default.
+ name := fmt.Sprintf("colab-output-%d%s", fileCount, ext)
+ if out.Filename != "" {
+ name = out.Filename
+ }
+ if outputDir != "" {
+ if err := os.MkdirAll(outputDir, 0o755); err != nil {
+ fmt.Fprintf(os.Stderr, "error creating %s: %v\n", outputDir, err)
+ }
+ name = filepath.Join(outputDir, name)
+ }
+ if err := os.WriteFile(name, data, 0o644); err != nil {
+ fmt.Fprintf(os.Stderr, "error saving %s: %v\n", mime, err)
+ } else {
+ fmt.Fprintf(os.Stderr, "Saved: %s\n", name)
+ }
+ break
+ }
+
+ switch out.Kind {
+ case colab.OutputStdout, colab.OutputResult:
+ fmt.Print(out.Text)
+ if len(out.Text) > 0 && out.Text[len(out.Text)-1] != '\n' {
+ fmt.Println()
+ }
+ case colab.OutputDisplay:
+ // Only print the text repr when there was no binary output saved.
+ if len(out.BinaryData) == 0 && out.Text != "" {
+ fmt.Print(out.Text)
+ if out.Text[len(out.Text)-1] != '\n' {
+ fmt.Println()
+ }
+ }
+ case colab.OutputStderr:
+ fmt.Fprint(os.Stderr, out.Text)
+ if len(out.Text) > 0 && out.Text[len(out.Text)-1] != '\n' {
+ fmt.Fprintln(os.Stderr)
+ }
+ case colab.OutputError:
+ fmt.Fprintln(os.Stderr, out.Text)
+ case colab.OutputStatus:
+ // busy/idle - not printed to the user.
+ case colab.OutputInputReq:
+ fmt.Printf("Input requested: %s", out.Text)
+ }
+ }
+}
+
+// notebookHash returns a fresh random notebook hash in the web-safe encoding
+// that the Colab assign endpoint expects as the nbh query parameter.
+//
+// Format: UUID-like hex string with dashes replaced by underscores, padded
+// with dots to 44 characters (mirrors uuid_to_web_safe_base64 in colab-cli).
+func notebookHash() string {
+ b := make([]byte, 16)
+ _, _ = rand.Read(b)
+ // Format as UUID groups: 8-4-4-4-12
+ h := hex.EncodeToString(b)
+ uuid := h[0:8] + "-" + h[8:12] + "-" + h[12:16] + "-" + h[16:20] + "-" + h[20:32]
+ // Replace dashes with underscores and pad to 44 chars with dots.
+ encoded := strings.ReplaceAll(uuid, "-", "_")
+ encoded += strings.Repeat(".", 44-len(uuid))
+ return encoded
+}
diff --git a/run.go b/run.go
new file mode 100644
index 0000000..41009f5
--- /dev/null
+++ b/run.go
@@ -0,0 +1,102 @@
+package main
+
+import (
+ "fmt"
+ "os"
+
+ "github.com/spf13/cobra"
+
+ "github.com/tetsuo/colabctl/internal/auth"
+ "github.com/tetsuo/colabctl/internal/colab"
+ "github.com/tetsuo/colabctl/internal/drive"
+ "github.com/tetsuo/colabctl/internal/notebook"
+)
+
+var runCmd = &cobra.Command{
+ Use: "run <file-id>",
+ Short: "Execute all code cells in a Colab notebook",
+ Long: `Starts a new Colab runtime for the given notebook (identified by its
+Drive file ID) and runs every code cell in order, printing the output.
+
+Get the file ID from:
+
+ colabctl list`,
+ Args: cobra.ExactArgs(1),
+ RunE: func(cmd *cobra.Command, args []string) error {
+ requireCredentials()
+
+ fileID := args[0]
+ ctx := cmd.Context()
+
+ httpClient, err := auth.Client(ctx, clientID, clientSecret)
+ if err != nil {
+ return err
+ }
+
+ // Download the notebook so we can iterate its cells.
+ fmt.Fprintf(os.Stderr, "Fetching notebook %s …\n", fileID)
+ driveClient, err := drive.New(ctx, httpClient)
+ if err != nil {
+ return err
+ }
+
+ raw, err := driveClient.GetNotebook(ctx, fileID)
+ if err != nil {
+ return err
+ }
+
+ nb, err := notebook.Parse(raw)
+ if err != nil {
+ return err
+ }
+
+ codeCells := nb.CodeCells()
+ if len(codeCells) == 0 {
+ fmt.Println("No code cells found in the notebook.")
+ return nil
+ }
+
+ accelerator, _ := cmd.Flags().GetString("accelerator")
+ outputDir, _ := cmd.Flags().GetString("output-dir")
+ fmt.Fprintf(os.Stderr, "Starting Colab runtime …\n")
+ colabClient := colab.New(httpClient)
+ assignment, err := colabClient.Assign(ctx, notebookHash(), "", accelerator)
+ if err != nil {
+ return fmt.Errorf("start runtime: %w", err)
+ }
+ fmt.Fprintf(os.Stderr, "Runtime assigned (endpoint %s)\n", assignment.Endpoint)
+
+ kernel, err := colab.CreateAndConnectKernel(ctx, assignment)
+ if err != nil {
+ return fmt.Errorf("connect to kernel: %w", err)
+ }
+ defer kernel.Close()
+
+ for i, cell := range codeCells {
+ code := cell.Source.String()
+ if code == "" {
+ continue
+ }
+
+ fmt.Printf("\n─── Cell %d ───────────────────────────────────\n", i+1)
+ fmt.Println(code)
+ fmt.Println("──────────────────────────────────────────────")
+
+ outCh, err := kernel.Execute(ctx, code)
+ if err != nil {
+ return fmt.Errorf("execute cell %d: %w", i+1, err)
+ }
+
+ printOutputs(outCh, outputDir)
+ }
+
+ fmt.Fprintln(os.Stderr, "\nAll cells executed.")
+ return nil
+ },
+}
+
+func init() {
+ runCmd.Flags().StringP("accelerator", "a", "", "Accelerator for the runtime: T4, A100, TPU, L4, A100-80GB (default: CPU)")
+ runCmd.Flags().StringP("output-dir", "o", "", "Directory to save binary outputs (images, audio, video) into (default: current directory)")
+ rootCmd.AddCommand(runCmd)
+}
diff --git a/sessions.go b/sessions.go
new file mode 100644
index 0000000..c3f0bf1
--- /dev/null
+++ b/sessions.go
@@ -0,0 +1,85 @@
+package main
+
+import (
+ "fmt"
+ "os"
+ "text/tabwriter"
+
+ "github.com/spf13/cobra"
+
+ "github.com/tetsuo/colabctl/internal/auth"
+ "github.com/tetsuo/colabctl/internal/colab"
+ "github.com/tetsuo/colabctl/internal/config"
+)
+
+var sessionsCmd = &cobra.Command{
+ Use: "sessions",
+ Aliases: []string{"ps"},
+ Short: "List active Colab runtimes on your account",
+ RunE: func(cmd *cobra.Command, _ []string) error {
+ requireCredentials()
+
+ httpClient, err := auth.Client(cmd.Context(), clientID, clientSecret)
+ if err != nil {
+ return err
+ }
+ client := colab.New(httpClient)
+
+ runtimes, err := client.ListAssignments(cmd.Context())
+ if err != nil {
+ return err
+ }
+
+ if len(runtimes) == 0 {
+ fmt.Println("No active runtimes.")
+ return nil
+ }
+
+ w := tabwriter.NewWriter(os.Stdout, 0, 0, 2, ' ', 0)
+ fmt.Fprintln(w, "ENDPOINT\tACCELERATOR\tURL")
+ fmt.Fprintln(w, "--------\t-----------\t---")
+ for _, r := range runtimes {
+ accel := r.Accelerator
+ if accel == "" {
+ accel = "CPU"
+ }
+ fmt.Fprintf(w, "%s\t%s\t%s\n", r.Endpoint, accel, r.URL)
+ }
+ return w.Flush()
+ },
+}
+
+var stopCmd = &cobra.Command{
+ Use: "stop <endpoint>",
+ Short: "Stop and release an active Colab runtime",
+ Long: `Terminates the runtime identified by its endpoint ID.
+Get the endpoint from:
+
+ colabctl sessions`,
+ Args: cobra.ExactArgs(1),
+ RunE: func(cmd *cobra.Command, args []string) error {
+ requireCredentials()
+
+ endpoint := args[0]
+ ctx := cmd.Context()
+
+ httpClient, err := auth.Client(ctx, clientID, clientSecret)
+ if err != nil {
+ return err
+ }
+ client := colab.New(httpClient)
+
+ fmt.Fprintf(os.Stderr, "Stopping runtime %s …\n", endpoint)
+ if err := client.Unassign(ctx, endpoint); err != nil {
+ return fmt.Errorf("stop runtime: %w", err)
+ }
+ _ = config.DeleteSession(endpoint)
+ fmt.Println("Runtime stopped.")
+ return nil
+ },
+}
+
+func init() {
+ rootCmd.AddCommand(sessionsCmd)
+ rootCmd.AddCommand(stopCmd)
+}