# How to Manage Browserbase Sessions with the bb CLI

> Manage Browserbase sessions effortlessly. Use the bb CLI to create, monitor, modify, and terminate remote Chromium instances. Integrate with CDP endpoints for seamless tool development.

- Repository: [browserbase/skills](https://github.com/browserbase/skills)
- Tags: how-to-guide
- Published: 2026-05-01

---

**Use the `bb sessions` subcommands to create, monitor, modify, and terminate remote Chromium instances via the Browserbase cloud platform, utilizing the returned `connectUrl` as a Chrome DevTools Protocol (CDP) endpoint for tool integration.**

The `bb` CLI, maintained in the `browserbase/skills` repository, provides a command-line interface to the Browserbase platform API. It allows you to manage short-lived, fully-featured Chromium sessions running in the cloud, complete with configurable proxies, stealth modes, and persistent storage contexts.

## Creating a New Session

Run `bb sessions create` to provision a remote browser instance. According to [`skills/browserbase-cli/SKILL.md`](https://github.com/browserbase/skills/blob/main/skills/browserbase-cli/SKILL.md) (lines 81-84), this command sends a POST request to the `/sessions` endpoint and returns JSON containing an `id` and a `connectUrl`. The `connectUrl` serves as a CDP endpoint that automation tools like Playwright, Puppeteer, or the `browser` skill can attach to.

```bash

# Create a session with proxy, stealth, and keep-alive enabled

SESSION_ID=$(bb sessions create \
  --proxies \
  --advanced-stealth \
  --region us-east-1 \
  --keep-alive \
  --timeout 600 \
  --output - | jq -r '.id')

echo "Created session: $SESSION_ID"

```

### Session Configuration Flags

As documented in [`skills/browserbase-cli/REFERENCE.md`](https://github.com/browserbase/skills/blob/main/skills/browserbase-cli/REFERENCE.md) (lines 36-49), the `create` command accepts several flags to customize the browser environment:

- **`--proxies`** – Enables Browserbase-managed IP rotation and geo-masking for the session.
- **`--advanced-stealth`** – Activates additional anti-bot evasion techniques including user-agent randomization and canvas spoofing.
- **`--solve-captchas` / `--no-solve-captchas`** – Toggles automatic CAPTCHA solving on or off.
- **`--region <region>`** – Specifies the data-center location (e.g., `us-east-1`, `eu-central-1`).
- **`--keep-alive`** – Maintains the session active after client disconnect, useful for background processing.
- **`--timeout <seconds>`** – Sets automatic session expiration after the specified duration.
- **`--persist`** – Saves cookies and localStorage changes to a Browserbase context for later reuse.
- **`--context-id <id>`** – Attaches the session to an existing persistent context rather than creating isolated storage.

## Inspecting Session Status

To retrieve a JSON snapshot of a running or completed session, use `bb sessions get <session_id>`. As noted in [`skills/browserbase-cli/REFERENCE.md`](https://github.com/browserbase/skills/blob/main/skills/browserbase-cli/REFERENCE.md) (lines 15-19), the response includes the session status (`RUNNING`, `COMPLETED`, etc.), proxy configuration, viewport dimensions, and any associated persisted context data.

```bash
bb sessions get "$SESSION_ID"

```

## Updating and Controlling Sessions

You can modify an active session's configuration or request a graceful shutdown using `bb sessions update`. The CLI merges supplied flags with the existing session body, as implemented in [`REFERENCE.md`](https://github.com/browserbase/skills/blob/main/REFERENCE.md) (lines 52-55). To terminate a session and release cloud resources, update the status to `REQUEST_RELEASE`.

```bash

# Gracefully shut down a session

bb sessions update "$SESSION_ID" --status REQUEST_RELEASE

```

For interactive debugging, `bb sessions debug` opens the DevTools UI for the specified session while it runs.

## Connecting External Tools via CDP

The `connectUrl` returned upon creation enables direct attachment via the Chrome DevTools Protocol. You can pass this endpoint to Playwright using `chromium.connectOverCDP()`, or use it with the `browse` sub-command (`bb browse env remote`), as referenced in [`SKILL.md`](https://github.com/browserbase/skills/blob/main/SKILL.md) (lines 60-62).

```javascript
import { chromium } from 'playwright';
import { readFileSync } from 'fs';

const session = JSON.parse(readFileSync('session.json'));
const browser = await chromium.connectOverCDP(session.connectUrl);
const page = await browser.newPage();
await page.goto('https://example.com');
console.log(await page.title());
await browser.close();

```

First generate the session file:

```bash
bb sessions get "$SESSION_ID" > session.json
node attach.mjs

```

## Persisting State Across Sessions

To maintain cookies and localStorage between automation runs, combine the `--persist` flag with a `--context-id`. This saves session state to a named Browserbase context that subsequent sessions can attach to, eliminating the need to re-authenticate or reconfigure browser state.

```bash

# Create a session attached to an existing persistent context

bb sessions create \
  --context-id ctx_12345 \
  --persist \
  --proxies \
  --region eu-central-1

```

## Retrieving Artifacts and Logs

After a session completes, download captured files, logs, or screenshot archives using `bb sessions downloads get`. As documented in [`REFERENCE.md`](https://github.com/browserbase/skills/blob/main/REFERENCE.md) (lines 26-28), this command retrieves artifacts generated during the session lifecycle.

```bash
bb sessions downloads get "$SESSION_ID" --output session-artifacts.zip

```

## Summary

- **Create** sessions with `bb sessions create`, capturing the `connectUrl` for CDP-based tool integration.
- **Configure** stealth, proxies, regions, and persistence using flags defined in [`skills/browserbase-cli/REFERENCE.md`](https://github.com/browserbase/skills/blob/main/skills/browserbase-cli/REFERENCE.md).
- **Monitor** session health and metadata via `bb sessions get <id>`.
- **Update** session parameters or trigger graceful termination with `bb sessions update --status REQUEST_RELEASE`.
- **Persist** authentication state across runs using `--persist` and `--context-id`.
- **Download** session artifacts after termination using `bb sessions downloads get`.

## Frequently Asked Questions

### How do I keep a Browserbase session alive after my script disconnects?

Use the `--keep-alive` flag when creating the session. This prevents the cloud infrastructure from terminating the Chromium instance when your local client disconnects, allowing background tasks to continue or enabling reconnection via the `connectUrl` later.

### Can I reuse cookies and login state between different bb CLI sessions?

Yes. Create a session with both `--persist` and `--context-id <id>` flags. The `--persist` flag saves cookies and localStorage to the specified context ID, which you can reference in subsequent `bb sessions create` commands to restore that browser state.

### What is the `connectUrl` used for in the bb sessions create response?

The `connectUrl` is a WebSocket endpoint implementing the Chrome DevTools Protocol (CDP). You pass this URL to automation libraries like Playwright (`chromium.connectOverCDP()`), Puppeteer, or Selenium to control the remote browser directly as if it were a local instance.

### How do I gracefully terminate a session and download its artifacts?

First, update the session status to `REQUEST_RELEASE` using `bb sessions update <id> --status REQUEST_RELEASE`. Once the session status changes to `COMPLETED`, retrieve any generated files using `bb sessions downloads get <id> --output <filename>`.