Skip to main content
This guide walks you through your first GSD Browser session. You will start the daemon, navigate to a page, take a snapshot to get versioned element refs, interact with those refs, and capture a screenshot. By the end, you will understand the core CLI workflow and know where to go next for AI agent integration.
Make sure you have installed GSD Browser and that Chrome or Chromium is available on your machine before continuing.

​
CLI quickstart

1

Start the daemon

The daemon starts automatically on the first browser command, but you can also pre-warm it explicitly:
Verify it is running:
2

Navigate to a URL

Send the browser to any page. The daemon opens Chrome if it isn’t already running.
You can combine navigation with an instant screenshot:
3

Take a snapshot to get element refs

A snapshot scans the current page and assigns stable versioned refs to every interactive element. Refs look like @v1:e1, @v1:e2, and so on. The version prefix ensures stale refs from a previous snapshot are automatically rejected.
Example output:
Always take a fresh snapshot after navigation or any DOM change. Old refs become stale when the page state changes. See Snapshots & Refs for a full explanation.
4

Click an element using its ref

Pass a ref directly to click. GSD Browser resolves it to the live DOM element — no CSS selector guessing required.
You can also click by CSS selector when you prefer:
5

Type into a field

Target an input by its ref and provide the text to type:
Add --submit to press Enter after typing, or --clear-first to empty the field before filling it:
6

Capture a screenshot

Save the current viewport as an image. Both JPEG and PNG are supported.
Capture the full scrollable page:
7

Stop the daemon

When you are done, stop the daemon and close the browser:

​
Useful CLI options

Every gsd-browser command accepts these global flags: For example, to get JSON output from a snapshot:

​
AI agent path: MCP server

If you are connecting an AI agent rather than scripting the CLI directly, use the MCP server instead. It exposes the full GSD Browser surface as 50+ discoverable tools, live resources, and executable prompts to any MCP-compatible client. Start the MCP server on stdio (most clients manage the process for you):
Or run it as an HTTP server for remote and cloud agents:

MCP Server guide

Client configuration, tool categories, resources, prompts, and remote hosting.

Snapshots & Refs

Deep dive into versioned refs — the core mechanism for reliable agent interaction.

​
What to explore next

Sessions

Isolate browser state, run parallel agent tasks, and persist authentication across runs.

Snapshots & Refs

Understand versioned refs, snapshot modes, and the action cache.

MCP Server

Connect Cursor, Claude Desktop, or any MCP-compatible agent.