nstbrowser-ai-agent

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

nstbrowser-ai-agent - Quick Reference

nstbrowser-ai-agent - 快速参考

Prerequisites

前置条件

Required: Nstbrowser desktop client must be installed and running

Download: https://www.nstbrowser.io/
Start the desktop application
Obtain API key from dashboard

必需条件：必须安装并运行Nstbrowser桌面客户端

下载链接：https://www.nstbrowser.io/
启动桌面应用程序
从控制面板获取API密钥

Quick Setup

快速设置

bash

undefined

bash

undefined

1. Configure API key (required)

nstbrowser-ai-agent config set key YOUR_API_KEY

2. Verify connection

nstbrowser-ai-agent profile list

3. Ready to use!

undefined

undefined

Core Commands

核心命令

Configuration

配置

bash

nstbrowser-ai-agent config set key YOUR_KEY    # Set API key
nstbrowser-ai-agent config show                # Show current config

bash

nstbrowser-ai-agent config set key YOUR_KEY    # Set API key
nstbrowser-ai-agent config show                # Show current config

Diagnostics & Troubleshooting

诊断与故障排除

bash

nstbrowser-ai-agent diagnose                   # Run comprehensive environment check
nstbrowser-ai-agent verify [--profile <name-or-id>]  # Test browser functionality
nstbrowser-ai-agent repair                     # Attempt automatic fixes

bash

nstbrowser-ai-agent diagnose                   # Run comprehensive environment check
nstbrowser-ai-agent verify [--profile <name-or-id>]  # Test browser functionality
nstbrowser-ai-agent repair                     # Attempt automatic fixes

Profile Management (NST)

配置文件管理（NST）

bash

nstbrowser-ai-agent profile list               # List all profiles
nstbrowser-ai-agent profile create <name>      # Create new profile
nstbrowser-ai-agent profile delete <id>        # Delete profile
nstbrowser-ai-agent profile proxy update <id>  # Update proxy settings
nstbrowser-ai-agent profile tags create <id> <tag> # Add tags to profile
nstbrowser-ai-agent profile cache clear <id>   # Clear profile cache

bash

nstbrowser-ai-agent profile list               # List all profiles
nstbrowser-ai-agent profile create <name>      # Create new profile
nstbrowser-ai-agent profile delete <id>        # Delete profile
nstbrowser-ai-agent profile proxy update <id>  # Update proxy settings
nstbrowser-ai-agent profile tags create <id> <tag> # Add tags to profile
nstbrowser-ai-agent profile cache clear <id>   # Clear profile cache

Browser Control (NST)

浏览器控制（NST）

bash

nstbrowser-ai-agent browser start-once         # Start temporary browser
nstbrowser-ai-agent browser list               # List running browsers
nstbrowser-ai-agent browser stop <id>          # Stop browser
nstbrowser-ai-agent browser start <profile-id> # Start browser for profile
nstbrowser-ai-agent browser stop-all           # Stop all browsers

bash

nstbrowser-ai-agent browser start-once         # Start temporary browser
nstbrowser-ai-agent browser list               # List running browsers
nstbrowser-ai-agent browser stop <id>          # Stop browser
nstbrowser-ai-agent browser start <profile-id> # Start browser for profile
nstbrowser-ai-agent browser stop-all           # Stop all browsers

Page Interaction

页面交互

All browser action commands support

[--profile <name-or-id>]

to specify which profile to use.

bash

nstbrowser-ai-agent open <url> [--profile <name-or-id>]               # Navigate to URL
nstbrowser-ai-agent snapshot -i [--profile <name-or-id>]              # Get interactive elements with refs
nstbrowser-ai-agent click @e1 [--profile <name-or-id>]                # Click element by ref
nstbrowser-ai-agent click @e1 --new-tab [--profile <name-or-id>]      # Click and open in new tab
nstbrowser-ai-agent fill @e2 "text" [--profile <name-or-id>]          # Fill input field
nstbrowser-ai-agent type @e2 "text" [--profile <name-or-id>]          # Type into element
nstbrowser-ai-agent hover @e3 [--profile <name-or-id>]                # Hover over element
nstbrowser-ai-agent focus @e4 [--profile <name-or-id>]                # Focus element
nstbrowser-ai-agent check @e5 [--profile <name-or-id>]                # Check checkbox
nstbrowser-ai-agent uncheck @e6 [--profile <name-or-id>]              # Uncheck checkbox
nstbrowser-ai-agent select @e7 "value" [--profile <name-or-id>]       # Select dropdown option
nstbrowser-ai-agent drag @e8 @e9 [--profile <name-or-id>]             # Drag and drop
nstbrowser-ai-agent upload @e10 ./file.pdf [--profile <name-or-id>]   # Upload files
nstbrowser-ai-agent download @e11 ./file.pdf [--profile <name-or-id>] # Download file

所有浏览器操作命令均支持

[--profile <name-or-id>]

参数以指定使用的配置文件。

bash

nstbrowser-ai-agent open <url> [--profile <name-or-id>]               # Navigate to URL
nstbrowser-ai-agent snapshot -i [--profile <name-or-id>]              # Get interactive elements with refs
nstbrowser-ai-agent click @e1 [--profile <name-or-id>]                # Click element by ref
nstbrowser-ai-agent click @e1 --new-tab [--profile <name-or-id>]      # Click and open in new tab
nstbrowser-ai-agent fill @e2 "text" [--profile <name-or-id>]          # Fill input field
nstbrowser-ai-agent type @e2 "text" [--profile <name-or-id>]          # Type into element
nstbrowser-ai-agent hover @e3 [--profile <name-or-id>]                # Hover over element
nstbrowser-ai-agent focus @e4 [--profile <name-or-id>]                # Focus element
nstbrowser-ai-agent check @e5 [--profile <name-or-id>]                # Check checkbox
nstbrowser-ai-agent uncheck @e6 [--profile <name-or-id>]              # Uncheck checkbox
nstbrowser-ai-agent select @e7 "value" [--profile <name-or-id>]       # Select dropdown option
nstbrowser-ai-agent drag @e8 @e9 [--profile <name-or-id>]             # Drag and drop
nstbrowser-ai-agent upload @e10 ./file.pdf [--profile <name-or-id>]   # Upload files
nstbrowser-ai-agent download @e11 ./file.pdf [--profile <name-or-id>] # Download file

Navigation & Waiting

导航与等待

bash

nstbrowser-ai-agent back [--profile <name-or-id>]                     # Go back
nstbrowser-ai-agent forward [--profile <name-or-id>]                  # Go forward
nstbrowser-ai-agent reload [--profile <name-or-id>]                   # Reload page
nstbrowser-ai-agent wait @e1 [--profile <name-or-id>]                 # Wait for element
nstbrowser-ai-agent wait 2000 [--profile <name-or-id>]                # Wait milliseconds
nstbrowser-ai-agent wait --load networkidle [--profile <name-or-id>]  # Wait for load state
nstbrowser-ai-agent wait --url "**/dashboard" [--profile <name-or-id>]  # Wait for URL pattern
nstbrowser-ai-agent wait --text "Welcome" [--profile <name-or-id>]    # Wait for text
nstbrowser-ai-agent wait --download ./file.pdf [--profile <name-or-id>]  # Wait for download

bash

nstbrowser-ai-agent back [--profile <name-or-id>]                     # Go back
nstbrowser-ai-agent forward [--profile <name-or-id>]                  # Go forward
nstbrowser-ai-agent reload [--profile <name-or-id>]                   # Reload page
nstbrowser-ai-agent wait @e1 [--profile <name-or-id>]                 # Wait for element
nstbrowser-ai-agent wait 2000 [--profile <name-or-id>]                # Wait milliseconds
nstbrowser-ai-agent wait --load networkidle [--profile <name-or-id>]  # Wait for load state
nstbrowser-ai-agent wait --url "**/dashboard" [--profile <name-or-id>]  # Wait for URL pattern
nstbrowser-ai-agent wait --text "Welcome" [--profile <name-or-id>]    # Wait for text
nstbrowser-ai-agent wait --download ./file.pdf [--profile <name-or-id>]  # Wait for download

Keyboard & Mouse

键盘与鼠标操作

bash

nstbrowser-ai-agent press Enter [--profile <name-or-id>]              # Press key
nstbrowser-ai-agent press Control+a [--profile <name-or-id>]          # Key combination
nstbrowser-ai-agent keyboard type "Hello" [--profile <name-or-id>]    # Type without selector
nstbrowser-ai-agent keyboard inserttext "text" [--profile <name-or-id>]  # Insert text
nstbrowser-ai-agent mouse move 100 200 [--profile <name-or-id>]       # Move mouse
nstbrowser-ai-agent mouse click [--profile <name-or-id>]              # Mouse click
nstbrowser-ai-agent scroll down 500 [--profile <name-or-id>]          # Scroll page
nstbrowser-ai-agent scrollintoview @e1 [--profile <name-or-id>]       # Scroll element into view

bash

nstbrowser-ai-agent press Enter [--profile <name-or-id>]              # Press key
nstbrowser-ai-agent press Control+a [--profile <name-or-id>]          # Key combination
nstbrowser-ai-agent keyboard type "Hello" [--profile <name-or-id>]    # Type without selector
nstbrowser-ai-agent keyboard inserttext "text" [--profile <name-or-id>]  # Insert text
nstbrowser-ai-agent mouse move 100 200 [--profile <name-or-id>]       # Move mouse
nstbrowser-ai-agent mouse click [--profile <name-or-id>]              # Mouse click
nstbrowser-ai-agent scroll down 500 [--profile <name-or-id>]          # Scroll page
nstbrowser-ai-agent scrollintoview @e1 [--profile <name-or-id>]       # Scroll element into view

Data Extraction

数据提取

bash

nstbrowser-ai-agent get title [--profile <name-or-id>]                # Get page title
nstbrowser-ai-agent get url [--profile <name-or-id>]                  # Get current URL
nstbrowser-ai-agent get text @e1 [--profile <name-or-id>]             # Get element text
nstbrowser-ai-agent get html @e2 [--profile <name-or-id>]             # Get element HTML
nstbrowser-ai-agent get value @e3 [--profile <name-or-id>]            # Get input value
nstbrowser-ai-agent get attr @e4 href [--profile <name-or-id>]        # Get attribute
nstbrowser-ai-agent get count "li.item" [--profile <name-or-id>]      # Count elements
nstbrowser-ai-agent get box @e5 [--profile <name-or-id>]              # Get bounding box
nstbrowser-ai-agent get styles @e6 [--profile <name-or-id>]           # Get computed styles
nstbrowser-ai-agent eval "document.title" [--profile <name-or-id>]    # Execute JavaScript

bash

nstbrowser-ai-agent get title [--profile <name-or-id>]                # Get page title
nstbrowser-ai-agent get url [--profile <name-or-id>]                  # Get current URL
nstbrowser-ai-agent get text @e1 [--profile <name-or-id>]             # Get element text
nstbrowser-ai-agent get html @e2 [--profile <name-or-id>]             # Get element HTML
nstbrowser-ai-agent get value @e3 [--profile <name-or-id>]            # Get input value
nstbrowser-ai-agent get attr @e4 href [--profile <name-or-id>]        # Get attribute
nstbrowser-ai-agent get count "li.item" [--profile <name-or-id>]      # Count elements
nstbrowser-ai-agent get box @e5 [--profile <name-or-id>]              # Get bounding box
nstbrowser-ai-agent get styles @e6 [--profile <name-or-id>]           # Get computed styles
nstbrowser-ai-agent eval "document.title" [--profile <name-or-id>]    # Execute JavaScript

Element State Checking

元素状态检查

bash

nstbrowser-ai-agent is visible @e1 [--profile <name-or-id>]           # Check if visible
nstbrowser-ai-agent is enabled @e2 [--profile <name-or-id>]           # Check if enabled
nstbrowser-ai-agent is checked @e3 [--profile <name-or-id>]           # Check if checked

bash

nstbrowser-ai-agent is visible @e1 [--profile <name-or-id>]           # Check if visible
nstbrowser-ai-agent is enabled @e2 [--profile <name-or-id>]           # Check if enabled
nstbrowser-ai-agent is checked @e3 [--profile <name-or-id>]           # Check if checked

Semantic Element Finding

语义化元素查找

bash

nstbrowser-ai-agent find role button click --name Submit
nstbrowser-ai-agent find text "Sign In" click
nstbrowser-ai-agent find label "Email" fill "user@example.com"
nstbrowser-ai-agent find placeholder "Search..." type "query"
nstbrowser-ai-agent find testid "login-form" click
nstbrowser-ai-agent find first "li.item" click
nstbrowser-ai-agent find nth 2 ".card" hover

bash

nstbrowser-ai-agent find role button click --name Submit
nstbrowser-ai-agent find text "Sign In" click
nstbrowser-ai-agent find label "Email" fill "user@example.com"
nstbrowser-ai-agent find placeholder "Search..." type "query"
nstbrowser-ai-agent find testid "login-form" click
nstbrowser-ai-agent find first "li.item" click
nstbrowser-ai-agent find nth 2 ".card" hover

Screenshots & Recording

截图与录制

bash

nstbrowser-ai-agent screenshot [path]          # Take screenshot
nstbrowser-ai-agent screenshot --full          # Full page screenshot
nstbrowser-ai-agent screenshot --annotate      # Annotated with element refs
nstbrowser-ai-agent pdf ./page.pdf             # Save as PDF
nstbrowser-ai-agent record start ./demo.webm   # Start video recording
nstbrowser-ai-agent record stop                # Stop recording

bash

nstbrowser-ai-agent screenshot [path]          # Take screenshot
nstbrowser-ai-agent screenshot --full          # Full page screenshot
nstbrowser-ai-agent screenshot --annotate      # Annotated with element refs
nstbrowser-ai-agent pdf ./page.pdf             # Save as PDF
nstbrowser-ai-agent record start ./demo.webm   # Start video recording
nstbrowser-ai-agent record stop                # Stop recording

Quick Start Workflows

快速开始工作流

Workflow 1: Temporary Browser (No Profile)

工作流1：临时浏览器（无配置文件）

bash

undefined

bash

undefined

Start temporary browser and navigate

nstbrowser-ai-agent browser start-once nstbrowser-ai-agent open https://example.com nstbrowser-ai-agent snapshot -i nstbrowser-ai-agent click @e1 nstbrowser-ai-agent close

undefined

nstbrowser-ai-agent browser start-once nstbrowser-ai-agent open https://example.com nstbrowser-ai-agent snapshot -i nstbrowser-ai-agent click @e1 nstbrowser-ai-agent close

undefined

Workflow 2: Profile-based Session (Recommended)

工作流2：基于配置文件的会话（推荐）

bash

undefined

bash

undefined

All browser commands can use --profile parameter

nstbrowser-ai-agent --profile my-profile open https://example.com nstbrowser-ai-agent --profile my-profile snapshot -i nstbrowser-ai-agent --profile my-profile fill @e1 "user@example.com" nstbrowser-ai-agent --profile my-profile fill @e2 "password" nstbrowser-ai-agent --profile my-profile click @e3 nstbrowser-ai-agent --profile my-profile close

Or use UUID format (auto-detected)

nstbrowser-ai-agent --profile "527e7b55-ca19-4422-89e4-88af4cf0f543" open https://example.com

undefined

nstbrowser-ai-agent --profile "527e7b55-ca19-4422-89e4-88af4cf0f543" open https://example.com

undefined

Workflow 3: Data Extraction with Profile

工作流3：基于配置文件的数据提取

bash

undefined

bash

undefined

Extract information from page using specific profile

nstbrowser-ai-agent --profile data-scraper open https://example.com nstbrowser-ai-agent --profile data-scraper wait --load networkidle nstbrowser-ai-agent --profile data-scraper snapshot -i nstbrowser-ai-agent --profile data-scraper get text @e1 nstbrowser-ai-agent --profile data-scraper eval "document.querySelectorAll('h2').length" nstbrowser-ai-agent --profile data-scraper screenshot --annotate page.png

undefined

undefined

Workflow 4: Advanced Automation with State Management

工作流4：带状态管理的高级自动化

bash

undefined

bash

undefined

Save authentication state for reuse

nstbrowser-ai-agent --profile auth-profile open https://app.example.com/login nstbrowser-ai-agent --profile auth-profile fill @e1 "user@example.com" nstbrowser-ai-agent --profile auth-profile fill @e2 "password" nstbrowser-ai-agent --profile auth-profile click @e3 nstbrowser-ai-agent --profile auth-profile wait --text "Dashboard" nstbrowser-ai-agent --profile auth-profile state save ./auth-state.json

Later, restore state and continue

nstbrowser-ai-agent --profile auth-profile state load ./auth-state.json nstbrowser-ai-agent --profile auth-profile open https://app.example.com/dashboard nstbrowser-ai-agent --profile auth-profile snapshot -i

undefined

undefined

Workflow 5: Multi-tab Operations

工作流5：多标签页操作

bash

undefined

bash

undefined

Work with multiple tabs using same profile

nstbrowser-ai-agent --profile multi-tab open https://example.com nstbrowser-ai-agent --profile multi-tab tab new https://another-site.com nstbrowser-ai-agent --profile multi-tab tab 1 # Switch to second tab nstbrowser-ai-agent --profile multi-tab click @e1 nstbrowser-ai-agent --profile multi-tab tab 0 # Switch back to first tab nstbrowser-ai-agent --profile multi-tab screenshot

undefined

undefined

Storage & Cookies Management

存储与Cookie管理

bash

nstbrowser-ai-agent cookies                    # Get all cookies
nstbrowser-ai-agent cookies set name "value"   # Set cookie
nstbrowser-ai-agent cookies set auth "token" --domain example.com --httpOnly --secure
nstbrowser-ai-agent cookies clear              # Clear all cookies
nstbrowser-ai-agent storage local              # Get localStorage
nstbrowser-ai-agent storage local set key "value" # Set localStorage
nstbrowser-ai-agent storage session get key    # Get sessionStorage
nstbrowser-ai-agent storage local clear        # Clear localStorage

bash

nstbrowser-ai-agent cookies                    # Get all cookies
nstbrowser-ai-agent cookies set name "value"   # Set cookie
nstbrowser-ai-agent cookies set auth "token" --domain example.com --httpOnly --secure
nstbrowser-ai-agent cookies clear              # Clear all cookies
nstbrowser-ai-agent storage local              # Get localStorage
nstbrowser-ai-agent storage local set key "value" # Set localStorage
nstbrowser-ai-agent storage session get key    # Get sessionStorage
nstbrowser-ai-agent storage local clear        # Clear localStorage

Network & Debugging

网络与调试

bash

nstbrowser-ai-agent network route "**/api/*" --abort # Block API requests
nstbrowser-ai-agent network route "**/data.json" --body '{"mock": true}'
nstbrowser-ai-agent network requests           # List captured requests
nstbrowser-ai-agent network requests --clear   # Clear request log
nstbrowser-ai-agent console                    # View console logs
nstbrowser-ai-agent errors                     # View page errors
nstbrowser-ai-agent trace start                # Start Playwright trace
nstbrowser-ai-agent trace stop ./trace.zip     # Stop and save trace
nstbrowser-ai-agent profiler start             # Start Chrome DevTools profiling
nstbrowser-ai-agent profiler stop ./profile.json # Stop and save profile

bash

nstbrowser-ai-agent network route "**/api/*" --abort # Block API requests
nstbrowser-ai-agent network route "**/data.json" --body '{"mock": true}'
nstbrowser-ai-agent network requests           # List captured requests
nstbrowser-ai-agent network requests --clear   # Clear request log
nstbrowser-ai-agent console                    # View console logs
nstbrowser-ai-agent errors                     # View page errors
nstbrowser-ai-agent trace start                # Start Playwright trace
nstbrowser-ai-agent trace stop ./trace.zip     # Stop and save trace
nstbrowser-ai-agent profiler start             # Start Chrome DevTools profiling
nstbrowser-ai-agent profiler stop ./profile.json # Stop and save profile

Tab & Window Management

标签页与窗口管理

bash

nstbrowser-ai-agent tab                        # List all tabs
nstbrowser-ai-agent tab new https://example.com # Open new tab
nstbrowser-ai-agent tab 2                      # Switch to tab 2
nstbrowser-ai-agent tab close                  # Close current tab
nstbrowser-ai-agent tab close 1                # Close tab 1
nstbrowser-ai-agent window new                 # Open new window
nstbrowser-ai-agent frame "#iframe"            # Switch to iframe
nstbrowser-ai-agent frame main                 # Switch back to main frame

bash

nstbrowser-ai-agent tab                        # List all tabs
nstbrowser-ai-agent tab new https://example.com # Open new tab
nstbrowser-ai-agent tab 2                      # Switch to tab 2
nstbrowser-ai-agent tab close                  # Close current tab
nstbrowser-ai-agent tab close 1                # Close tab 1
nstbrowser-ai-agent window new                 # Open new window
nstbrowser-ai-agent frame "#iframe"            # Switch to iframe
nstbrowser-ai-agent frame main                 # Switch back to main frame

Browser Settings & Emulation

浏览器设置与模拟

bash

nstbrowser-ai-agent set viewport 1920 1080     # Set viewport size
nstbrowser-ai-agent set device "iPhone 12"     # Emulate device
nstbrowser-ai-agent set geo 37.7749 -122.4194  # Set geolocation
nstbrowser-ai-agent set offline on             # Enable offline mode
nstbrowser-ai-agent set headers '{"X-Custom": "value"}' # Set HTTP headers
nstbrowser-ai-agent set credentials admin pass # Set HTTP auth
nstbrowser-ai-agent set media dark             # Set color scheme

bash

nstbrowser-ai-agent set viewport 1920 1080     # Set viewport size
nstbrowser-ai-agent set device "iPhone 12"     # Emulate device
nstbrowser-ai-agent set geo 37.7749 -122.4194  # Set geolocation
nstbrowser-ai-agent set offline on             # Enable offline mode
nstbrowser-ai-agent set headers '{"X-Custom": "value"}' # Set HTTP headers
nstbrowser-ai-agent set credentials admin pass # Set HTTP auth
nstbrowser-ai-agent set media dark             # Set color scheme

State Management

状态管理

bash

nstbrowser-ai-agent state save ./auth-state.json # Save browser state
nstbrowser-ai-agent state load ./auth-state.json # Load browser state
nstbrowser-ai-agent state list                 # List saved states
nstbrowser-ai-agent state show filename.json   # Show state summary
nstbrowser-ai-agent state clear --all          # Clear all states

bash

nstbrowser-ai-agent state save ./auth-state.json # Save browser state
nstbrowser-ai-agent state load ./auth-state.json # Load browser state
nstbrowser-ai-agent state list                 # List saved states
nstbrowser-ai-agent state show filename.json   # Show state summary
nstbrowser-ai-agent state clear --all          # Clear all states

Comparison & Diffing

对比与差异检测

bash

nstbrowser-ai-agent diff snapshot              # Compare current vs last snapshot
nstbrowser-ai-agent diff snapshot --baseline before.txt # Compare vs saved snapshot
nstbrowser-ai-agent diff screenshot --baseline before.png # Visual diff
nstbrowser-ai-agent diff url https://v1.com https://v2.com # Compare two pages
nstbrowser-ai-agent diff url https://staging.com https://prod.com --screenshot

bash

nstbrowser-ai-agent diff snapshot              # Compare current vs last snapshot
nstbrowser-ai-agent diff snapshot --baseline before.txt # Compare vs saved snapshot
nstbrowser-ai-agent diff screenshot --baseline before.png # Visual diff
nstbrowser-ai-agent diff url https://v1.com https://v2.com # Compare two pages
nstbrowser-ai-agent diff url https://staging.com https://prod.com --screenshot

Dialog Handling

对话框处理

bash

nstbrowser-ai-agent dialog accept              # Accept alert/confirm
nstbrowser-ai-agent dialog accept "input text" # Accept prompt with text
nstbrowser-ai-agent dialog dismiss             # Dismiss/cancel dialog

bash

nstbrowser-ai-agent dialog accept              # Accept alert/confirm
nstbrowser-ai-agent dialog accept "input text" # Accept prompt with text
nstbrowser-ai-agent dialog dismiss             # Dismiss/cancel dialog

Global Options (Apply to ALL commands)

全局选项（适用于所有命令）

Profile Selection

配置文件选择

bash

--profile <name-or-id>     # Use specific NST profile (name or UUID)
                          # Examples: --profile "my-profile" or --profile "527e7b55-ca19-4422-89e4-88af4cf0f543"

bash

--profile <name-or-id>     # Use specific NST profile (name or UUID)
                          # Examples: --profile "my-profile" or --profile "527e7b55-ca19-4422-89e4-88af4cf0f543"

Session Management

会话管理

bash

--session <name>          # Use isolated session
--session-name <name>     # Auto-save/restore state across restarts

bash

--session <name>          # Use isolated session
--session-name <name>     # Auto-save/restore state across restarts

Output Control

输出控制

bash

--json                    # JSON output for all commands
--content-boundaries      # Wrap page content in boundary markers
--max-output <chars>      # Truncate output to N characters

bash

--json                    # JSON output for all commands
--content-boundaries      # Wrap page content in boundary markers
--max-output <chars>      # Truncate output to N characters

Browser Configuration

浏览器配置

bash

--headers <json>          # HTTP headers (scoped to origin)
--user-agent <ua>         # Custom User-Agent
--proxy <server>          # Proxy server (http://user:pass@host:port)
--proxy-bypass <hosts>    # Bypass proxy for hosts
--color-scheme <scheme>   # dark, light, no-preference
--download-path <path>    # Default download directory

bash

--headers <json>          # HTTP headers (scoped to origin)
--user-agent <ua>         # Custom User-Agent
--proxy <server>          # Proxy server (http://user:pass@host:port)
--proxy-bypass <hosts>    # Bypass proxy for hosts
--color-scheme <scheme>   # dark, light, no-preference
--download-path <path>    # Default download directory

Common Issues & Solutions

常见问题与解决方案

Problem	Solution
"HTTP 400: Bad Request"	Start Nstbrowser desktop client and verify API key
"Profile not found"	Use `profile list` to see available profiles, or check profile name/ID
"Element not found"	Run `snapshot -i` to refresh element refs after page changes
"@e1 not working"	Element refs change after navigation - get fresh snapshot
"Browser not running"	Use `browser start <profile-id>` or `browser start-once`
"Command timeout"	Use appropriate wait strategies: `wait --load networkidle`
"Stale element reference"	Re-run `snapshot -i` after DOM changes
"Profile ID vs name confusion"	Both work - UUID format auto-detected as ID, others as name
"Headers not working"	Headers are scoped to origin - use `--headers` with `open` command
"Download not saving"	Specify full path: `download @e1 ./downloads/file.pdf`
"Screenshot annotation missing"	Use `--annotate` flag: `screenshot --annotate`
"State not persisting"	Use `--session-name` for auto-persistence or manual `state save/load`

问题	解决方案
"HTTP 400: Bad Request"	启动Nstbrowser桌面客户端并验证API密钥
"Profile not found"	使用 `profile list` 查看可用配置文件，或检查配置文件名称/ID
"Element not found"	页面变更后运行 `snapshot -i` 以刷新元素引用
"@e1 not working"	导航后元素引用会变更 - 获取新的快照
"Browser not running"	使用 `browser start <profile-id>` 或 `browser start-once` 启动浏览器
"Command timeout"	使用合适的等待策略： `wait --load networkidle`
"Stale element reference"	DOM变更后重新运行 `snapshot -i`
"Profile ID vs name confusion"	两者均可用 - UUID格式会被自动识别为ID，其他则视为名称
"Headers not working"	头信息是基于源域的 - 在 `open` 命令中使用 `--headers` 参数
"Download not saving"	指定完整路径： `download @e1 ./downloads/file.pdf`
"Screenshot annotation missing"	使用 `--annotate` 参数： `screenshot --annotate`
"State not persisting"	使用 `--session-name` 实现自动持久化，或手动执行 `state save/load`

Advanced Features

高级特性

Proxy Configuration:

profile proxy update <id> --host proxy.com --port 8080

Batch Operations:
```
profile delete id1 id2 id3
```
Tab Management:
```
tab new <url>
```
,
```
tab 0
```
,
```
tab close
```
Wait Strategies:
```
wait 3000
```
,
```
wait --load networkidle
```

代理配置：

profile proxy update <id> --host proxy.com --port 8080

批量操作：
```
profile delete id1 id2 id3
```
标签页管理：
```
tab new <url>
```
,
```
tab 0
```
,
```
tab close
```
等待策略：
```
wait 3000
```
,
```
wait --load networkidle
```

Best Practices

最佳实践

Always Use Profile Parameters: Specify
```
--profile <name-or-id>
```
for all browser operations to ensure consistent fingerprinting and session management
Profile ID vs Name: Use profile IDs (UUID format) for reliability, names for readability - both are auto-detected
Refresh Element References: Run
```
snapshot -i
```
after tab switches, page changes, or navigation to get fresh @e references
Use JSON Output for Integration: Add
```
--json
```
to any command for machine-readable output in AI agent workflows
Handle Async Operations: Use appropriate wait strategies (
```
--load networkidle
```
,
```
wait --text
```
,
```
wait @element
```
) for dynamic content
State Persistence: Use
```
--session-name
```
for automatic state persistence across browser restarts
Error Handling: Check command output and retry with fresh snapshots if element references become stale
Security: Use
```
--content-boundaries
```
to safely parse page content and avoid injection attacks
Performance: Use
```
--max-output
```
to limit large page content,
```
snapshot --compact
```
to reduce noise
Debugging: Use
```
--annotate
```
screenshots for visual debugging,
```
trace start/stop
```
for detailed analysis

始终使用配置文件参数：所有浏览器操作均需指定
```
--profile <name-or-id>
```
参数，以确保一致的指纹伪装与会话管理
配置文件ID与名称：使用配置文件ID（UUID格式）以保证可靠性，使用名称以提升可读性 - 两者均会被自动识别
刷新元素引用：切换标签页、页面变更或导航后，运行
```
snapshot -i
```
以获取最新的@e引用
使用JSON输出进行集成：在任何命令后添加
```
--json
```
参数，以获取适合AI Agent工作流的机器可读输出
处理异步操作：针对动态内容使用合适的等待策略（
```
--load networkidle
```
、
```
wait --text
```
、
```
wait @element
```
）
状态持久化：使用
```
--session-name
```
实现浏览器重启后的自动状态持久化
错误处理：检查命令输出，若元素引用失效则重新获取快照并重试
安全性：使用
```
--content-boundaries
```
安全解析页面内容，避免注入攻击
性能优化：使用
```
--max-output
```
限制大页面内容输出，使用
```
snapshot --compact
```
减少冗余信息
调试：使用
```
--annotate
```
截图进行可视化调试，使用
```
trace start/stop
```
进行详细分析

Profile Parameter Usage

配置文件参数使用说明

All browser action commands support the
--profile
parameter:

bash

undefined

所有浏览器操作命令均支持
--profile
参数：

bash

undefined

Navigation commands

nstbrowser-ai-agent --profile my-profile open <url> nstbrowser-ai-agent --profile my-profile back nstbrowser-ai-agent --profile my-profile forward nstbrowser-ai-agent --profile my-profile reload

Interaction commands

nstbrowser-ai-agent --profile my-profile click @e1 nstbrowser-ai-agent --profile my-profile fill @e2 "text" nstbrowser-ai-agent --profile my-profile type @e3 "text" nstbrowser-ai-agent --profile my-profile hover @e4 nstbrowser-ai-agent --profile my-profile drag @e5 @e6

Data extraction commands

nstbrowser-ai-agent --profile my-profile snapshot -i nstbrowser-ai-agent --profile my-profile get text @e1 nstbrowser-ai-agent --profile my-profile screenshot nstbrowser-ai-agent --profile my-profile eval "code"

State and storage commands

nstbrowser-ai-agent --profile my-profile cookies set name "value" nstbrowser-ai-agent --profile my-profile storage local set key "value" nstbrowser-ai-agent --profile my-profile state save ./state.json

All other browser commands...


**Profile Resolution Priority:**
1. Check running browsers (by ID or name, use earliest if multiple)
2. Start browser if profile exists but not running  
3. Create new profile if name doesn't exist
4. Error if ID doesn't exist
5. Use temporary browser if no profile specified


**配置文件解析优先级**：
1. 检查运行中的浏览器（通过ID或名称，若有多个则使用最早启动的）
2. 若配置文件存在但未运行，则启动浏览器  
3. 若名称不存在，则创建新的配置文件
4. 若ID不存在，则返回错误
5. 若未指定配置文件，则使用临时浏览器

Full Documentation

完整文档

Complete documentation: https://github.com/nstbrowser/nstbrowser-ai-agent#readme

完整文档：https://github.com/nstbrowser/nstbrowser-ai-agent#readme

Notes

注意事项

All browser operations use Nstbrowser profiles for advanced fingerprinting
Temporary browsers (
```
browser start-once
```
) don't save session state
Profile sessions persist cookies, localStorage, and login state
Element refs (@e1, @e2) are generated by
```
snapshot -i
```
command

所有浏览器操作均使用Nstbrowser配置文件以实现高级指纹伪装
临时浏览器（
```
browser start-once
```
）不会保存会话状态
配置文件会话会保留Cookie、localStorage和登录状态
元素引用（@e1、@e2）由
```
snapshot -i
```
命令生成