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:

agent-browser cookies

Output:

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

cookies set

Set a cookie.

Parameter	Description
name	Cookie name
value	Cookie value

Options:

Option	Description
—url	URL to set cookie for
—domain	Cookie domain
—path	Cookie path (default: /)
—httpOnly	HttpOnly flag
—secure	Secure flag
—sameSite	SameSite attribute: Strict, Lax, None
—expires	Expiration timestamp (Unix epoch)

Examples:

# 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:

agent-browser cookies clear

Local Storage

storage local

Get all localStorage items.

Examples:

agent-browser storage local

Output:

{
  "theme": "dark",
  "language": "en",
  "user_preferences": "{\"notifications\":true}"
}

storage local (key)

Get specific localStorage item.

Parameter	Description
key	Storage key

Examples:

agent-browser storage local theme
agent-browser storage local user_preferences

Output:

dark

storage local set

Set localStorage item.

Parameter	Description
key	Storage key
value	Storage value

Examples:

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:

agent-browser storage local clear

Session Storage

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

Examples:

# 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.

Parameter	Description
path	File path to save state

Examples:

# 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.

Parameter	Description
path	File path to load state from

Examples:

# 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:

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.

Parameter	Description
filename	State file name

Examples:

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.

Parameter	Description
name	Optional: Session name to clear

Options:

Option	Description
—all, -a	Clear all saved states

Examples:

# 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.

Option	Description
—older-than	Delete states older than N days

Examples:

# 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.

Parameter	Description
old-name	Current state file name
new-name	New state file name

Examples:

agent-browser state rename old-state.json new-state.json
agent-browser state rename test production

Workflow Examples

Skip Login Flow

# Login once and save state
agent-browser open example.com/login
agent-browser fill @e1 "[e-mail]"
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

# 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

# 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

# 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

# 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:

# 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:

# 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

Variable	Description
AGENT_BROWSER_SESSION_NAME	Auto-save/load state with this name
AGENT_BROWSER_ENCRYPTION_KEY	64-char hex key for AES-256-GCM encryption
AGENT_BROWSER_STATE_EXPIRE_DAYS	Auto-delete states older than N days (default: 30)