Skip to main content
Session management commands control the background daemon that powers every gsd-browser operation, named browser sessions that let you run parallel instances, the live authenticated viewer, and the encrypted credential vault. Most users never need to start or stop the daemon manually — it auto-starts on the first command and shuts down when no longer needed — but these commands give you full control when you need it.

​
Daemon Commands

The gsd-browser daemon is the long-running background process that owns the Chrome instance and handles all CDP communication. Each named session gets its own daemon process.

​
gsd-browser daemon start

Start the background daemon. You rarely need to call this directly; any gsd-browser command will auto-start the daemon if one is not already running.
Example

​
gsd-browser daemon stop

Stop the running daemon for the current (or specified) session. The Chrome process managed by that daemon is also terminated.
Example

​
gsd-browser daemon health

Check whether the daemon is running and healthy. Returns the daemon status and any error reason. This command does not start the daemon if it is not already running.
Example

​
Session State Commands

Use --session <name> on any command to target a named parallel browser instance. Named sessions share no cookies, storage, or page state with each other. The following commands let you persist and restore an entire browser context (cookies, localStorage, sessionStorage) across runs.

​
gsd-browser save-state

Save the current browser context (cookies, local storage, session storage) to disk under a named profile.
​
string
Profile name for the saved state. Defaults to "default" when omitted.
Example

​
gsd-browser restore-state

Restore a previously saved browser context from disk, loading cookies and storage without navigating or logging in again.
​
string
Profile name of the state to restore. Defaults to "default" when omitted.
Example

​
Viewer Commands

The live viewer lets you watch and interact with an active browser session through a web-based UI, protected by a rotating auth token. Share the viewer URL with a teammate to give them real-time visibility into an automation run.

​
gsd-browser view

Open the live viewer for the current session. GSD Browser prints a localhost URL and opens it in your default browser.
​
flag
Print the viewer URL without opening it in a browser. Useful when you need to pass the URL to another tool.
​
flag
Open the history-focused viewer, showing a scrollable timeline of past actions rather than the live frame.
Example
The viewer URL contains an authentication token. Treat it like a password — do not commit it to source control or share it in public channels.

​
Vault Commands

The vault stores credentials encrypted at rest, keyed by a profile name. The daemon decrypts credentials only when needed to perform a login. Set the GSD_BROWSER_VAULT_KEY environment variable before starting the daemon to enable vault encryption.

​
gsd-browser vault-save

Store a set of credentials in the encrypted vault under a profile name.
​
string
required
A unique profile name for this credential set (e.g. my-app-prod).
​
string
required
The login URL for this credential profile.
​
string
required
The username or email address for this credential.
​
string
required
The password. This value is encrypted at rest using the GSD_BROWSER_VAULT_KEY environment variable.
Example

​
gsd-browser vault-list

List all vault profile names. Credentials (usernames and passwords) are never shown.
Example

​
gsd-browser vault-login

Navigate to the login URL stored in a vault profile and automatically fill and submit the login form using the stored credentials.
​
string
required
The profile name of the credentials to use for login.
Example
Combine vault-login with save-state to capture an authenticated browser state that you can restore with restore-state in future runs, avoiding repeated login flows.