Skip to main content

​
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.
ParameterDescription
nameCookie name
valueCookie value
Options:
OptionDescription
—urlURL to set cookie for
—domainCookie domain
—pathCookie path (default: /)
—httpOnlyHttpOnly flag
—secureSecure flag
—sameSiteSameSite attribute: Strict, Lax, None
—expiresExpiration 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.
ParameterDescription
keyStorage key
Examples: 
agent-browser storage local theme
agent-browser storage local user_preferences
Output: 
dark

​
storage local set

Set localStorage item.
ParameterDescription
keyStorage key
valueStorage 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.
ParameterDescription
pathFile 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.
ParameterDescription
pathFile 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.
ParameterDescription
filenameState 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.
ParameterDescription
nameOptional: Session name to clear
Options:
OptionDescription
—all, -aClear 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.
OptionDescription
—older-thanDelete 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.
ParameterDescription
old-nameCurrent state file name
new-nameNew 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 "[email protected]"
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

# 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

VariableDescription
AGENT_BROWSER_SESSION_NAMEAuto-save/load state with this name
AGENT_BROWSER_ENCRYPTION_KEY64-char hex key for AES-256-GCM encryption
AGENT_BROWSER_STATE_EXPIRE_DAYSAuto-delete states older than N days (default: 30)

Build docs developers (and LLMs) love

Get started for freeTalk to us