Browser automation CLI with Nstbrowser integration for AI agents. Use when the user needs advanced browser fingerprinting, profile management, proxy configur...
This skill enables AI agents to control browsers using nstbrowser-ai-agent CLI with Nstbrowser integration. Nstbrowser provides advanced browser fingerprinting, profile management, and anti-detection capabilities for professional browser automation.
This tool requires Nstbrowser service to function. All browser operations are performed through Nstbrowser profiles, which provide:
Before using this tool, ensure you have the following:
Nstbrowser client must be installed and running on your system.
The Nstbrowser API service must be accessible:
http://127.0.0.1:8848nstbrowser-ai-agent profile list
Obtain your API key from the Nstbrowser dashboard and configure it:
Method 1: Config File (Recommended)
nstbrowser-ai-agent config set key YOUR_API_KEY
Method 2: Environment Variable
Set the NST_API_KEY environment variable in your shell configuration file.
Install the nstbrowser-ai-agent CLI:
# Using npx (no installation required)
npx nstbrowser-ai-agent --help
# Or install globally
npm install -g nstbrowser-ai-agent
Test your setup:
# Check CLI version
nstbrowser-ai-agent --version
# List profiles (verifies API connection)
nstbrowser-ai-agent profile list
If you see your profiles or an empty list, your environment is configured correctly.
Get started in 5 minutes with these examples:
For quick tests or one-time tasks:
# 1. Start temporary browser
nstbrowser-ai-agent browser start-once
# 2. Open a website
nstbrowser-ai-agent open https://example.com
# 3. Take a snapshot
nstbrowser-ai-agent snapshot -i
# 4. Close browser (auto-cleanup)
nstbrowser-ai-agent close
Note: Temporary browsers don't save session state and are cleaned up after use.
For tasks that require saved sessions, cookies, or login state:
# 1. List available profiles
nstbrowser-ai-agent profile list
# 2. Create a new profile (if needed)
nstbrowser-ai-agent profile create my-profile
# 3. Open browser with profile (auto-starts if not running)
nstbrowser-ai-agent open https://example.com
# 4. Interact with page
nstbrowser-ai-agent snapshot -i
nstbrowser-ai-agent click @e1
# 5. Close browser (session saved to profile)
nstbrowser-ai-agent close
Expected Output:
Profiles are the foundation of Nstbrowser automation. Each profile is an isolated browser environment that stores:
Why use profiles?
All profile commands support both profile NAME and profile ID:
Profile Name:
my-profile, test-account, production-botProfile ID:
86581051-fb0d-4c4a-b1e3-ebc1abd17174UUID Format Auto-Detection:
--profile, it's treated as a profile ID--profile "86581051-fb0d-4c4a-b1e3-ebc1abd17174" is treated as profile IDResolution Priority:
--profile flag (profile name or UUID auto-detected as ID)Profile Resolution Logic: When you specify a profile for a browser action:
Important: If multiple profiles have the same name, the earliest started browser will be used.
Once you start a session with a profile, that session "locks" to that browser instance. Subsequent commands automatically reuse the same browser without repeating the --profile flag.
# First command: link session to profile
nstbrowser-ai-agent --profile my-profile open https://example.com
# Subsequent commands: Stays in 'my-profile' automatically
nstbrowser-ai-agent snapshot -i
nstbrowser-ai-agent click @e1
nstbrowser-ai-agent fill @e2 "data"
This makes automation scripts cleaner and reduces the need to specify the profile repeatedly.
Elements are identified by refs (e.g., @e1, @e2) from snapshots, making automation more reliable than CSS selectors.
# Get snapshot with refs
nstbrowser-ai-agent snapshot -i
# Output shows elements with refs:
# @e1 button "Submit"
# @e2 textbox "Email"
# @e3 textbox "Password"
# Use refs to interact
nstbrowser-ai-agent fill @e2 "user@example.com"
nstbrowser-ai-agent fill @e3 "password"
nstbrowser-ai-agent click @e1
Note: For modern web frameworks (React, Vue, Angular), CSS selectors may be more reliable than refs.
Store configuration persistently in ~/.nst-ai-agent/config.json:
# Set API key (required)
nstbrowser-ai-agent config set key YOUR_API_KEY
# Optional: Set custom host
nstbrowser-ai-agent config set host api.example.com
# Optional: Set custom port
nstbrowser-ai-agent config set port 9000
# View all configuration
nstbrowser-ai-agent config show
# Get specific value
nstbrowser-ai-agent config get key
Configuration persists across sessions and takes priority over environment variables.
Alternative to config file:
# Nstbrowser API credentials (required if not using config)
# Set NST_API_KEY in your environment
# Optional: Nstbrowser API endpoint
# Set NST_HOST and NST_PORT if using custom endpoint
# Optional: Specify profile for each command
# nstbrowser-ai-agent open https://example.com --profile "my-profile"
Priority: Config file > Environment variables > Defaults
List Profiles
# List all profiles
nstbrowser-ai-agent profile list
# List with JSON output
nstbrowser-ai-agent profile list --json
# List with pagination (for large datasets)
nstbrowser-ai-agent profile list-cursor --page-size 50
Show Profile Details
# Show by name or ID
nstbrowser-ai-agent profile show my-profile --json
nstbrowser-ai-agent profile show 86581051-fb0d-4c4a-b1e3-ebc1abd17174 --json
Create Profile
nstbrowser-ai-agent profile create my-profile \
--proxy-host proxy.example.com \
--proxy-port 8080 \
--proxy-type http \
--platform Windows
Delete Profile
# Delete single profile
nstbrowser-ai-agent profile delete <profile-name-or-id>
# Delete multiple profiles
nstbrowser-ai-agent profile delete id-1 id-2 id-3
Start Browser
# Start with profile name
nstbrowser-ai-agent browser start my-profile
# Start with profile ID
nstbrowser-ai-agent browser start 86581051-fb0d-4c4a-b1e3-ebc1abd17174
# Start temporary browser
nstbrowser-ai-agent browser start-once
# Start temporary browser
nstbrowser-ai-agent browser start-once
Stop Browser
# Stop specific browser
nstbrowser-ai-agent browser stop my-profile
# Stop all browsers
nstbrowser-ai-agent browser stop-all
List Running Browsers
nstbrowser-ai-agent browser list
Open URL
# Auto-launches browser if not running
nstbrowser-ai-agent open https://example.com
Navigate
nstbrowser-ai-agent back
nstbrowser-ai-agent forward
nstbrowser-ai-agent reload
Get Snapshot
# Accessibility snapshot with refs (best for AI)
nstbrowser-ai-agent snapshot -i
# Compact snapshot
nstbrowser-ai-agent snapshot -c
# Custom depth
nstbrowser-ai-agent snapshot -d 3
Get Page Info
nstbrowser-ai-agent get title
nstbrowser-ai-agent get url
Take Screenshot
nstbrowser-ai-agent screenshot output.png
# Annotated screenshot with element labels
nstbrowser-ai-agent screenshot --annotate output.png
Click
# Click by ref
nstbrowser-ai-agent click @e1
# Click by CSS selector
nstbrowser-ai-agent click 'button[type="submit"]'
Fill Input
# Fill by ref
nstbrowser-ai-agent fill @e2 "text"
# Fill by CSS selector
nstbrowser-ai-agent fill 'input[name="email"]' "user@example.com"
Type Text
nstbrowser-ai-agent type @e3 "text"
Get Element Text
nstbrowser-ai-agent get text @e4
nstbrowser-ai-agent get text '.product-price'
Wait for Element
nstbrowser-ai-agent wait 'button.submit'
Wait for Time
# Wait 3 seconds
nstbrowser-ai-agent wait 3000
Wait for Page Load
nstbrowser-ai-agent wait --load networkidle
Execute JavaScript
nstbrowser-ai-agent eval "document.title"
nstbrowser-ai-agent eval "document.querySelectorAll('a').length"
# Execute from stdin
echo "document.body.innerHTML" | nstbrowser-ai-agent eval --stdin
Show Proxy
nstbrowser-ai-agent profile proxy show my-profile --json
Update Proxy
nstbrowser-ai-agent profile proxy update my-profile \
--host proxy.example.com \
--port 8080 \
--type http \
--username proxyuser \
--password proxypass
Reset Proxy
nstbrowser-ai-agent profile proxy reset <profile-name-or-id>
Batch Proxy Operations
# Batch update
nstbrowser-ai-agent profile proxy batch-update id-1 id-2 id-3 \
--host proxy.example.com \
--port 8080 \
--type http
# Batch reset
nstbrowser-ai-agent profile proxy batch-reset id-1 id-2 id-3
Use Case: Automate tasks that require persistent login sessions or cookies.
# 1. List profiles to verify connection
nstbrowser-ai-agent profile list
# 2. Set profile by name
nstbrowser-ai-agent config set profile my-profile
# 3. List profiles to find target
nstbrowser-ai-agent profile list
# 4. Open browser with profile (auto-starts if not running)
nstbrowser-ai-agent open https://example.com --profile "my-profile"
nstbrowser-ai-agent open https://example.com
# 6. Get snapshot
nstbrowser-ai-agent snapshot -i
# 7. Interact with page
nstbrowser-ai-agent click @e1
nstbrowser-ai-agent fill @e2 "data"
# 8. Close (session saved to profile)
nstbrowser-ai-agent close
Use Case: Manage multiple profiles efficiently (update proxies, add tags, organize).
# Get multiple profile IDs
PROFILE_IDS=$(nstbrowser-ai-agent profile list --json | jq -r '.data.profiles[0:3] | map(.profileId) | join(" ")')
# Batch update proxy
nstbrowser-ai-agent profile proxy batch-update $PROFILE_IDS \
--host proxy.example.com \
--port 8080 \
--type http
# Batch add tags
nstbrowser-ai-agent profile tags batch-create $PROFILE_IDS \
automated:blue batch-updated:green
# Batch move to group
GROUP_ID=$(nstbrowser-ai-agent profile groups list --json | jq -r '.data.groups[0].groupId')
nstbrowser-ai-agent profile groups batch-change $GROUP_ID $PROFILE_IDS
Use Case: Log in to a website, navigate to data pages, and extract information.
# 1. Open login page
nstbrowser-ai-agent --profile my-profile open https://site.com/login
# 2. Wait for page to load
nstbrowser-ai-agent wait --load networkidle
# 3. Fill and submit using CSS selectors
nstbrowser-ai-agent fill 'input[placeholder="Email"]' "user@example.com"
nstbrowser-ai-agent fill 'input[type="password"]' "userpassword"
nstbrowser-ai-agent click 'button[type="submit"]'
# 4. Wait for navigation
nstbrowser-ai-agent wait --load networkidle
# 5. Navigate to target page
nstbrowser-ai-agent open https://site.com/data
# 6. Extract data
nstbrowser-ai-agent snapshot -i > data.txt
nstbrowser-ai-agent eval "document.querySelector('.info')?.textContent"
# 7. Close (session saved to profile)
nstbrowser-ai-agent close
Cause: API key not configured.
Solution:
# Method 1: Config file (recommended)
nstbrowser-ai-agent config set key YOUR_API_KEY
# Method 2: Set environment variable in your shell
Verify:
nstbrowser-ai-agent config get key
Cause: Nstbrowser service not running or wrong endpoint.
Solution:
nstbrowser-ai-agent nst status
nstbrowser-ai-agent config set host YOUR_HOST
nstbrowser-ai-agent config set port YOUR_PORT
Verify:
# Should show "NST agent is running and responsive"
nstbrowser-ai-agent nst status
# Should return list of profiles
nstbrowser-ai-agent profile list
Cause: Specified profile doesn't exist.
Solution:
nstbrowser-ai-agent profile list
nstbrowser-ai-agent profile create my-profile
nstbrowser-ai-agent browser start-once
Verify:
# Should show your profile
nstbrowser-ai-agent profile show my-profile
Cause: Element ref is stale or page structure changed.
Solution:
nstbrowser-ai-agent snapshot -i
# Instead of: nstbrowser-ai-agent click @e1
# Use: nstbrowser-ai-agent click 'button[type="submit"]'
nstbrowser-ai-agent eval "Array.from(document.querySelectorAll('input')).map(el => ({type: el.type, placeholder: el.placeholder}))"
Verify:
# Element should be visible
nstbrowser-ai-agent is visible 'button[type="submit"]'
The ref system (@e1, @e2, etc.) may not work reliably with modern web frameworks (Vue.js, React, Angular) due to dynamic DOM updates.
Workaround - Use CSS Selectors:
# 1. Inspect page elements
nstbrowser-ai-agent eval "Array.from(document.querySelectorAll('input')).map(el => ({type: el.type, placeholder: el.placeholder}))"
# 2. Use CSS selectors directly
nstbrowser-ai-agent fill 'input[placeholder="Email"]' "user@example.com"
nstbrowser-ai-agent fill 'input[type="password"]' "password"
nstbrowser-ai-agent click 'button[type="submit"]'
profile list - List all profilesprofile list-cursor - List profiles with cursor paginationprofile show <name-or-id> - Show profile detailsprofile create <name> - Create new profileprofile delete <name-or-id> [name-or-id...] - Delete profile(s)profile groups list - List all groupsprofile groups change <group-id> <profile-name-or-id> [...] - Move profile(s) to groupprofile groups batch-change <group-id> <id> [...] - Batch change groupprofile cache clear <id> [id...] - Clear profile cacheprofile cookies clear <id> [id...] - Clear profile cookiesprofile proxy show <name-or-id> - Show proxy configurationprofile proxy update <name-or-id> - Update proxy settingsprofile proxy reset <id> [id...] - Reset proxy settingsprofile proxy batch-update <id> [id...] - Batch update proxyprofile proxy batch-reset <id> [id...] - Batch reset proxyprofile tags list - List all tagsprofile tags create <id> <tag> - Add tag to profileprofile tags update <id> <tag:color> [...] - Update profile tagsprofile tags clear <id> [id...] - Clear profile tagsprofile tags batch-create <id> [id...] <tag:color> - Batch create tagsprofile tags batch-update <id> [id...] <tag:color> - Batch update tagsprofile tags batch-clear <id> [id...] - Batch clear tagsbrowser list - List running browsersbrowser start <name-or-id> - Start browser with profilebrowser start-once - Start temporary browserbrowser stop <name-or-id> - Stop browserbrowser stop-all - Stop all browsersbrowser pages <name-or-id> - Get browser pages listbrowser debugger <name-or-id> - Get debugger URLbrowser cdp-url <name-or-id> - Get CDP WebSocket URLbrowser cdp-url-once - Get CDP URL for temporary browserbrowser connect <name-or-id> - Connect and get CDP URLbrowser connect-once - Connect to temporary browser and get CDP URLopen <url> - Navigate to URLback - Go backforward - Go forwardreload - Reload pagesnapshot [-i] [-c] [-d <depth>] - Get page snapshotget title - Get page titleget url - Get current URLget text <sel> - Get element textscreenshot [path] - Take screenshotis visible <sel> - Check if element is visibleclick <sel> - Click elementfill <sel> <text> - Fill inputtype <sel> <text> - Type into elementpress <key> - Press keywait <sel|ms> - Wait for element or timeeval <js> - Execute JavaScriptclose - Close browsersession list - List active sessionsupdate check - Check for available updatesnst status - Check if NST agent is runningconfig set <key> <value> - Set configurationconfig get <key> - Get configuration valueconfig show - Show all configurationAll commands support --json flag for machine-readable output:
nstbrowser-ai-agent profile list --json
nstbrowser-ai-agent snapshot -i --json
nstbrowser-ai-agent get text @e1 --json
--profile flag once browser is runningwait --load networkidle after navigationnstbrowser-ai-agent update check periodicallyThe CLI automatically checks for updates once every 24 hours and notifies you when a new version is available.
Disable automatic checks:
# Set environment variable
NSTBROWSER_AI_AGENT_NO_UPDATE_CHECK=1
# Check for updates
nstbrowser-ai-agent update check
# JSON output
nstbrowser-ai-agent update check --json
# If installed globally
npm install -g nstbrowser-ai-agent@latest
# If using npx
npx nstbrowser-ai-agent@latest
# If installed locally in project
npm install nstbrowser-ai-agent@latest
For more detailed information, see:
| Reference | When to Use |
|---|---|
| references/nst-api-reference.md | Complete NST API reference with all commands |
| references/profile-management.md | Profile creation, organization, and lifecycle |
| references/proxy-configuration.md | Proxy setup, testing, and troubleshooting |
| references/batch-operations.md | Efficient batch operations on multiple profiles |
| references/troubleshooting.md | Common issues and diagnostic commands |
| Template | Description |
|---|---|
| templates/profile-setup.sh | Profile initialization with proxy and tags |
| templates/batch-proxy-update.sh | Batch proxy update for multiple profiles |
| templates/automated-workflow.sh | Complete automation workflow example |
./templates/profile-setup.sh my-profile --proxy-host proxy.com --proxy-port 8080
./templates/batch-proxy-update.sh "id1 id2 id3" --proxy-host proxy.com --proxy-port 8080
./templates/automated-workflow.sh my-profile https://example.com
browser start-once for disposable sessions that don't save stateGet Chrome DevTools Protocol (CDP) WebSocket URLs to connect external tools:
# Get CDP URL for existing browser
nstbrowser-ai-agent browser cdp-url my-profile
# Get CDP URL for temporary browser
nstbrowser-ai-agent browser cdp-url-once
# Connect to browser and get CDP URL (starts if not running)
nstbrowser-ai-agent browser connect my-profile
# Connect to temporary browser and get CDP URL
nstbrowser-ai-agent browser connect-once
Use cases:
ZIP package — ready to use