> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/vercel-labs/agent-browser/llms.txt
> Use this file to discover all available pages before exploring further.

# State Management Commands

> Manage cookies, storage, and browser state

## Overview

State management commands allow you to control cookies, localStorage, sessionStorage, and save/load browser state.

## Cookies

### cookies

Get all cookies for the current page.

**Examples:**

```bash theme={null}
agent-browser cookies
```

**Output:**

```json theme={null}
[
  {
    "name": "session_id",
    "value": "abc123",
    "domain": ".example.com",
    "path": "/",
    "expires": 1709395200,
    "httpOnly": true,
    "secure": true,
    "sameSite": "Lax"
  }
]
```

### cookies set

Set a cookie.

<table>
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>name</code></td>
      <td>Cookie name</td>
    </tr>

    <tr>
      <td><code>value</code></td>
      <td>Cookie value</td>
    </tr>
  </tbody>
</table>

**Options:**

<table>
  <thead>
    <tr>
      <th>Option</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>--url</code></td>
      <td>URL to set cookie for</td>
    </tr>

    <tr>
      <td><code>--domain</code></td>
      <td>Cookie domain</td>
    </tr>

    <tr>
      <td><code>--path</code></td>
      <td>Cookie path (default: /)</td>
    </tr>

    <tr>
      <td><code>--httpOnly</code></td>
      <td>HttpOnly flag</td>
    </tr>

    <tr>
      <td><code>--secure</code></td>
      <td>Secure flag</td>
    </tr>

    <tr>
      <td><code>--sameSite</code></td>
      <td>SameSite attribute: Strict, Lax, None</td>
    </tr>

    <tr>
      <td><code>--expires</code></td>
      <td>Expiration timestamp (Unix epoch)</td>
    </tr>
  </tbody>
</table>

**Examples:**

```bash theme={null}
# Set simple cookie
agent-browser cookies set session_id abc123

# Set cookie with domain
agent-browser cookies set user_id 456 --domain ".example.com"

# Set secure cookie
agent-browser cookies set token xyz --secure --httpOnly

# Set cookie with SameSite
agent-browser cookies set auth token123 --sameSite Strict

# Set cookie with expiration (Unix timestamp)
agent-browser cookies set temp value --expires 1709395200

# Set cookie for specific URL
agent-browser cookies set api_key key123 --url "https://api.example.com"
```

### cookies clear

Clear all cookies.

**Examples:**

```bash theme={null}
agent-browser cookies clear
```

## Local Storage

### storage local

Get all localStorage items.

**Examples:**

```bash theme={null}
agent-browser storage local
```

**Output:**

```json theme={null}
{
  "theme": "dark",
  "language": "en",
  "user_preferences": "{\"notifications\":true}"
}
```

### storage local (key)

Get specific localStorage item.

<table>
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>key</code></td>
      <td>Storage key</td>
    </tr>
  </tbody>
</table>

**Examples:**

```bash theme={null}
agent-browser storage local theme
agent-browser storage local user_preferences
```

**Output:**

```
dark
```

### storage local set

Set localStorage item.

<table>
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>key</code></td>
      <td>Storage key</td>
    </tr>

    <tr>
      <td><code>value</code></td>
      <td>Storage value</td>
    </tr>
  </tbody>
</table>

**Examples:**

```bash theme={null}
agent-browser storage local set theme dark
agent-browser storage local set language en
agent-browser storage local set user_id 12345
```

### storage local clear

Clear all localStorage.

**Examples:**

```bash theme={null}
agent-browser storage local clear
```

## Session Storage

Session storage commands work identically to local storage, but use `storage session` instead:

**Examples:**

```bash theme={null}
# Get all sessionStorage
agent-browser storage session

# Get specific key
agent-browser storage session tab_state

# Set value
agent-browser storage session form_data "{\"name\":\"John\"}"

# Clear all
agent-browser storage session clear
```

## Browser State

### state save

Save current browser state (cookies, localStorage, sessionStorage) to a file.

<table>
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>path</code></td>
      <td>File path to save state</td>
    </tr>
  </tbody>
</table>

**Examples:**

```bash theme={null}
# Save state after login
agent-browser state save ./auth-state.json

# Save state with descriptive name
agent-browser state save ./logged-in-user.json
```

**Output:**

```
State saved to ./auth-state.json
```

### state load

Load browser state from a file.

<table>
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>path</code></td>
      <td>File path to load state from</td>
    </tr>
  </tbody>
</table>

**Examples:**

```bash theme={null}
# Load saved state
agent-browser state load ./auth-state.json

# Navigate to page with loaded state
agent-browser open example.com/dashboard
```

**Output:**

```
State loaded from ./auth-state.json
```

### state list

List all saved state files.

**Examples:**

```bash theme={null}
agent-browser state list
```

**Output:**

```
Saved state files:
  auth-state.json (2.3 KB, 2026-03-01)
  logged-in-user.json (1.8 KB, 2026-02-28)
  test-session.json (3.1 KB, 2026-02-27)
```

### state show

Show summary of a state file.

<table>
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>filename</code></td>
      <td>State file name</td>
    </tr>
  </tbody>
</table>

**Examples:**

```bash theme={null}
agent-browser state show auth-state.json
```

**Output:**

```
State file: auth-state.json
Size: 2.3 KB
Created: 2026-03-01 14:30:00
Cookies: 5
LocalStorage: 3 items
SessionStorage: 1 item
```

### state clear

Clear saved state files.

<table>
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>name</code></td>
      <td>Optional: Session name to clear</td>
    </tr>
  </tbody>
</table>

**Options:**

<table>
  <thead>
    <tr>
      <th>Option</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>--all, -a</code></td>
      <td>Clear all saved states</td>
    </tr>
  </tbody>
</table>

**Examples:**

```bash theme={null}
# Clear states for current session
agent-browser state clear

# Clear states for specific session
agent-browser state clear mysession

# Clear all saved states
agent-browser state clear --all
```

### state clean

Delete old state files.

<table>
  <thead>
    <tr>
      <th>Option</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>--older-than</code></td>
      <td>Delete states older than N days</td>
    </tr>
  </tbody>
</table>

**Examples:**

```bash theme={null}
# Delete states older than 30 days
agent-browser state clean --older-than 30

# Delete states older than 7 days
agent-browser state clean --older-than 7
```

### state rename

Rename a state file.

<table>
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>old-name</code></td>
      <td>Current state file name</td>
    </tr>

    <tr>
      <td><code>new-name</code></td>
      <td>New state file name</td>
    </tr>
  </tbody>
</table>

**Examples:**

```bash theme={null}
agent-browser state rename old-state.json new-state.json
agent-browser state rename test production
```

## Workflow Examples

### Skip Login Flow

```bash theme={null}
# Login once and save state
agent-browser open example.com/login
agent-browser fill @e1 "user@example.com"
agent-browser fill @e2 "password"
agent-browser click @e3
agent-browser wait --url "**/dashboard"
agent-browser state save ./logged-in.json

# Reuse saved state (skip login)
agent-browser state load ./logged-in.json
agent-browser open example.com/dashboard
# Already logged in!
```

### Session Management

```bash theme={null}
# Save different user sessions
agent-browser state save ./user1-session.json
agent-browser state save ./user2-session.json

# Switch between users
agent-browser state load ./user1-session.json
agent-browser open example.com/dashboard

# Switch to user2
agent-browser state load ./user2-session.json
agent-browser open example.com/dashboard
```

### Testing with Different States

```bash theme={null}
# Test as logged-in user
agent-browser state load ./logged-in.json
agent-browser open example.com/protected

# Test as guest
agent-browser cookies clear
agent-browser storage local clear
agent-browser open example.com/protected
# Should redirect to login
```

### Manage User Preferences

```bash theme={null}
# Set theme preference
agent-browser storage local set theme dark

# Set language
agent-browser storage local set language en

# Get current theme
agent-browser storage local theme

# Clear preferences
agent-browser storage local clear
```

### Cookie-Based Auth

```bash theme={null}
# Set auth cookie
agent-browser cookies set auth_token xyz123 --secure --httpOnly

# Navigate to protected page
agent-browser open example.com/dashboard

# Verify cookie exists
agent-browser cookies

# Clear session
agent-browser cookies clear
```

## Persistent Sessions

Use `--session-name` to automatically save and restore state:

```bash theme={null}
# Auto-save/load state
export AGENT_BROWSER_SESSION_NAME=myapp
agent-browser open example.com

# State persists across browser restarts
agent-browser close
agent-browser open example.com
# Cookies and storage restored automatically
```

## State Encryption

Encrypt saved state files with AES-256-GCM:

```bash theme={null}
# Generate encryption key
openssl rand -hex 32

# Set encryption key
export AGENT_BROWSER_ENCRYPTION_KEY=<64-char-hex-key>

# State files are now encrypted
agent-browser --session-name secure open example.com
```

## Environment Variables

<table>
  <thead>
    <tr>
      <th>Variable</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>AGENT\_BROWSER\_SESSION\_NAME</code></td>
      <td>Auto-save/load state with this name</td>
    </tr>

    <tr>
      <td><code>AGENT\_BROWSER\_ENCRYPTION\_KEY</code></td>
      <td>64-char hex key for AES-256-GCM encryption</td>
    </tr>

    <tr>
      <td><code>AGENT\_BROWSER\_STATE\_EXPIRE\_DAYS</code></td>
      <td>Auto-delete states older than N days (default: 30)</td>
    </tr>
  </tbody>
</table>