Feature request: adopt/connect to an existing Colab backend session from the CLI

[Formatted]

Summary

I’d like to propose adding a CLI command that lets users adopt an already-active Colab backend session into local google-colab-cli state.

Proposed command:

colab adopt -s browser-session --endpoint <endpoint>

After adoption, the existing backend session could be used with the normal CLI workflow:

colab status -s browser-session
colab exec -s browser-session -f train.py
colab console -s browser-session
colab url -s browser-session --open

Problem

Right now, colab sessions can show active backend assignments, including sessions that were not originally created by the CLI on the current machine/config.

However, if a backend session is not present in local sessions.json, there does not appear to be a supported way to assign it a local session name and continue using it through the CLI.

That means a user can have an active Colab runtime, see it from the CLI, but not cleanly run:

colab exec -s my-existing-session -f script.py

unless the CLI created that session originally.

Why this matters

The new Colab CLI is especially useful for terminal-based, scripted, and agentic workflows.

In real workflows, though, users and agents do not always start from a clean colab new.

Common cases:

• A user already has a Colab runtime open in the browser.
• A notebook/runtime was started before the CLI entered the workflow.
• An agent needs to continue work from an existing runtime instead of provisioning a new one.
• A developer wants to move from browser-first experimentation to terminal-driven execution.

Being able to adopt an existing backend session would make this handoff much smoother.

Proposed behavior

Adopt by endpoint

colab adopt -s browser-session --endpoint <endpoint>

This would write a local SessionState entry for the selected backend assignment.

Adopt automatically when only one untracked backend exists

colab adopt -s browser-session

If exactly one untracked backend assignment exists, the CLI can adopt it without requiring --endpoint.

Require endpoint when multiple untracked backends exist

If multiple untracked backend sessions exist, the command should fail with guidance:

[colab] Multiple untracked backend sessions found.
Run `colab sessions` and retry with:
  colab adopt -s NAME --endpoint ENDPOINT

Conflict handling

If the endpoint is already tracked under another local session name, the command should fail unless --force is provided.

If the same name already points to the same endpoint, the command should be idempotent and exit successfully without side effects.

Keep-alive

By default, adoption should start the same keep-alive behavior used by CLI-created sessions.

Users should also be able to skip that:

colab adopt -s browser-session --endpoint <endpoint> --no-keep-alive

Prototype

I implemented this in a fork to validate the behavior:

https://github.com/Formatted/google-colab-cli/tree/adopt-existing-session

The prototype includes:

• colab adopt -s NAME
• optional --endpoint
• optional --force
• optional --no-keep-alive
• idempotent re-adoption of the same name/endpoint
• conflict handling
• runtime proxy validation
• keep-alive support
• docs
• tests
• real StateStore test proving status works after adoption

Local test suite result:

227 passed

I know this repo is not currently accepting external PRs, so I’m posting this here as a feature request / design discussion rather than opening a PR.

Open questions

1. Would maintainers expect this command to be named adopt, attach, or something else?

2. Should adoption start keep-alive by default, or should it only persist local state?

3. Should colab sessions include a hint when it displays an untracked session, such as:

   Run `colab adopt -s NAME --endpoint ENDPOINT` to use this session from the CLI.
   

Request

Would this be useful as a supported CLI workflow?

I’d love feedback from maintainers and Colab CLI users on whether adopting existing backend sessions should be first-class behavior.

[teeler]

yea we have colab url for going the other way (cli --> browser), but it sounds like you're wanting to go from the browser --> CLI?

[teeler]

@sethtroisi and @spencersgoogle fyi