notte-browser

Notte 浏览器命令行工具

使用 notte.cc 平台进行浏览器自动化、网页抓取和 AI 驱动的网页交互的命令行界面。

快速入门

# 1. Authenticate
notte auth login

# 2. Start a browser session
notte sessions start

# 3. Goto and observe
notte page goto "https://example.com"
notte page observe
notte page screenshot

# 4. Execute actions (use @IDs from observe, or Playwright selectors)
notte page click "@B3"
notte page fill "@I1" "hello world"
# If @IDs don't work, use Playwright selectors:
# notte page click "button:has-text('Submit')"

# 5. Scrape content
notte page scrape --instructions "Extract all product names and prices"

# 6. Stop the session
notte sessions stop

命令类别

会话管理

控制浏览器会话的生命周期：

# Start a new session
notte sessions start [flags]
  --headless                 Run in headless mode (default: true)
  --idle-timeout-minutes     Idle timeout in minutes
  --max-duration-minutes     Maximum session lifetime in minutes
  --proxy                    Use default proxies
  --proxy-country <code>     Proxy country code (e.g. us, gb, fr)
  --solve-captchas           Automatically solve captchas
  --viewport-width           Viewport width in pixels
  --viewport-height          Viewport height in pixels
  --user-agent               Custom user agent string
  --cdp-url                  CDP URL of remote session provider
  --use-file-storage         Enable file storage for the session

# Get current session status
notte sessions status

# Stop current session
notte sessions stop

# List sessions (with optional pagination and filters)
notte sessions list [--page N] [--page-size N] [--only-active]

注意： 启动会话后，它会自动成为“当前”会话（即设置 NOTTE_SESSION_ID 环境变量）。之后的所有命令默认都使用此会话。只有在需要同时管理多个会话或引用特定会话时，才使用 --session-id <session-id>。

会话调试与导出：

# Get network logs
notte sessions network

# Get replay URL/data
notte sessions replay

# Export session steps as Python workflow code
notte sessions workflow-code

Cookie 管理：

# Get all cookies
notte sessions cookies

# Set cookies from JSON file
notte sessions cookies-set --file cookies.json

页面操作

用于页面交互的简化命令：

元素交互：

# Click an element (use either the ids from an observe, or a selector)
notte page click "@B3"
notte page click "#submit-button"
  --timeout     Timeout in milliseconds
  --enter       Press Enter after clicking

# Fill an input field
notte page fill "@I1" "hello world"
  --clear       Clear field before filling
  --enter       Press Enter after filling

# Check/uncheck a checkbox
notte page check "#my-checkbox"
  --value       true to check, false to uncheck (default: true)

# Select dropdown option
notte page select "#dropdown-element" "Option 1"

# Download file by clicking element
notte page download "@L5"

# Upload file to input
notte page upload "#file-input" --file /path/to/file

# Run JavaScript in the Page
- Escape single quotes if needed.
- Don’t use logging (output won’t be captured).
- Use a single statement or a function that returns a value.

# Single expression
notte page eval-js 'document.title'

# Function with return value
notte page eval-js '
() => {
  const els = document.querySelectorAll("a");
  return els.length;
}
'

导航：

notte page goto "https://example.com"
notte page new-tab "https://example.com"
notte page back
notte page forward
notte page reload

滚动：

notte page scroll-down [amount]
notte page scroll-up [amount]

键盘：

notte page press "Enter"
notte page press "Escape"
notte page press "Tab"

标签页管理：

notte page switch-tab 1
notte page close-tab

页面状态：

# Observe page state and available actions
notte page observe

# Save a screenshot in tmp folder
notte page screenshot

# Scrape content with instructions
notte page scrape --instructions "Extract all links" [--only-main-content]

实用工具：

# Wait for specified duration
notte page wait 1000

# Solve CAPTCHA
notte page captcha-solve "recaptcha"

# Mark task complete
notte page complete "Task finished successfully" [--success=true]

# Fill form with JSON data
notte page form-fill --data '{"email": "[email protected]", "name": "John"}'

AI Agent

启动和管理 AI 驱动的浏览器 Agent：

# List all agents (with optional pagination and filters)
notte agents list [--page N] [--page-size N] [--only-active] [--only-saved]

# Start a new agent (auto-uses current session if active)
notte agents start --task "Navigate to example.com and extract the main heading"
  --session-id             Session ID (uses current session if not specified)
  --vault-id               Vault ID for credential access
  --persona-id             Persona ID for identity
  --max-steps              Maximum steps for the agent (default: 30)
  --reasoning-model        Custom reasoning model

# Get current agent status
notte agents status

# Stop current agent
notte agents stop

# Export agent steps as workflow code
notte agents workflow-code

# Get agent execution replay
notte agents replay

注意： 启动 Agent 后，它会自动成为“当前”Agent（保存到 ~/.notte/cli/current_agent）。之后的所有命令默认都使用此 Agent。只有在需要同时管理多个 Agent 或引用特定 Agent 时，才使用 --agent-id <agent-id>。

Agent ID 解析顺序：

1. --agent-id 标志（优先级最高）
2. NOTTE_AGENT_ID 环境变量
3. ~/.notte/cli/current_agent 文件（优先级最低）

函数（工作流自动化）

创建、管理和调度可重复使用的工作流：

# List all functions (with optional pagination and filters)
notte functions list [--page N] [--page-size N] [--only-active]

# Create a function from a workflow file
notte functions create --file workflow.py [--name "My Function"] [--description "..."] [--shared]

# Show current function details
notte functions show

# Update current function code
notte functions update --file workflow.py

# Delete current function
notte functions delete

# Run current function
notte functions run

# List runs for current function (with optional pagination and filters)
notte functions runs [--page N] [--page-size N] [--only-active]

# Stop a running function execution
notte functions run-stop --run-id <run-id>

# Get run logs and results
notte functions run-metadata --run-id <run-id>

# Schedule current function with cron expression
notte functions schedule --cron "0 9 * * *"

# Remove schedule from current function
notte functions unschedule

# Fork a shared function to your account
notte functions fork --function-id <shared-function-id>

注意： 创建函数后，它会自动成为“当前”函数。之后的所有命令默认都使用此函数。只有在需要同时管理多个函数或引用特定函数时（例如派生共享函数），才使用 --function-id <function-id>。

账户管理

Persona —— 带有电子邮件的自动生成身份：

# List personas (with optional pagination and filters)
notte personas list [--page N] [--page-size N] [--only-active]

# Create a persona
notte personas create [--create-vault]

# Show persona details
notte personas show --persona-id <persona-id>

# Delete a persona
notte personas delete --persona-id <persona-id>

# List emails received by persona
notte personas emails --persona-id <persona-id>

# List SMS messages received
notte personas sms --persona-id <persona-id>

Vault —— 存储自己的凭据：

# List vaults (with optional pagination and filters)
notte vaults list [--page N] [--page-size N] [--only-active]

# Create a vault
notte vaults create [--name "My Vault"]

# Update vault name
notte vaults update --vault-id <vault-id> --name "New Name"

# Delete a vault
notte vaults delete --vault-id <vault-id>

# Manage credentials
notte vaults credentials list --vault-id <vault-id>
notte vaults credentials add --vault-id <vault-id> --url "https://site.com" --password "pass" [--email "..."] [--username "..."] [--mfa-secret "..."]
notte vaults credentials get --vault-id <vault-id> --url "https://site.com"
notte vaults credentials delete --vault-id <vault-id> --url "https://site.com"

全局选项

所有命令均可使用：

--output, -o    Output format: text, json (default: text)
--timeout       API request timeout in seconds (default: 30)
--no-color      Disable color output
--verbose, -v   Verbose output
--yes, -y       Skip confirmation prompts

环境变量

变量	描述
NOTTE_API_KEY	用于身份验证的 API 密钥
NOTTE_SESSION_ID	默认会话 ID（无需使用 --session-id 标志）
NOTTE_API_URL	自定义 API 端点 URL

会话 ID 解析顺序

会话 ID 按以下顺序解析：

1. --session-id 标志
2. NOTTE_SESSION_ID 环境变量
3. 当前会话文件（由 sessions start 自动设置）

示例

基础网页抓取

# Scrape with session
notte sessions start --headless
notte page goto "https://news.ycombinator.com"
notte page scrape --instructions "Extract top 10 story titles"
notte sessions stop

# Multi-page scraping
notte sessions start --headless
notte page goto "https://example.com/products"
notte page observe
notte page scrape --instructions "Extract product names and prices"
notte page click "@L3"
notte page scrape --instructions "Extract product names and prices"
notte sessions stop

表单自动化

notte sessions start
notte page goto "https://example.com/signup"
notte page fill "#email-field" "[email protected]"
notte page fill "#password-field" "securepassword"
notte page click "#submit-button"
notte sessions stop

使用 Vault 的已认证会话

# Setup credentials once
notte vaults create --name "MyService"
notte vaults credentials add --vault-id <vault-id> \
  --url "https://myservice.com" \
  --email "[email protected]" \
  --password "mypassword" \
  --mfa-secret "JBSWY3DPEHPK3PXP"

# Use in automation (vault credentials auto-fill on matching URLs)
notte sessions start
notte page goto "https://myservice.com/login"
# Credentials from vault are used automatically
notte sessions stop

定时收集数据

# Create workflow file
cat > collect_data.py << 'EOF'
# Notte workflow script
# ...
EOF

# Upload as function
notte functions create --file collect_data.py --name "Daily Data Collection"

# Schedule to run every day at 9 AM
notte functions schedule --function-id <function-id> --cron "0 9 * * *"

# Check run history
notte functions runs --function-id <function-id>

提示与故障排除

处理不一致的 observe 输出

observe 命令有时可能会返回过时或不完整的 DOM 状态，尤其是在动态内容、模态框或单页应用中。如果输出看起来不正确：

1. 使用屏幕截图进行确认：notte page screenshot 始终显示当前的视觉状态
2. 改用 Playwright 选择器：不要使用 @ID 引用，而是使用 #id、.class 或 button:has-text('Submit') 等标准选择器
3. 稍作等待：观察之前运行 notte page wait 500，有助于处理动态内容

选择器语法

支持 observe 返回的元素 ID 和 Playwright 选择器：

# Using element IDs from observe output
notte page click "@B3"
notte page fill "@I1" "text"

# Using Playwright selectors (recommended when @IDs don't work)
notte page click "#submit-button"
notte page click ".btn-primary"
notte page click "button:has-text('Submit')"
notte page click "[data-testid='login']"
notte page fill "input[name='email']" "[email protected]"

处理多个匹配项 —— 使用 >> nth=0 选择第一个匹配项：

# When multiple elements match, select by index
notte page click "button:has-text('OK') >> nth=0"
notte page click ".submit-btn >> nth=0"

处理模态框和对话框

模态框和弹出窗口可能会干扰页面交互。提示：

• 按 Escape 关闭模态框：notte page press "Escape" 可以可靠地关闭大多数对话框和模态框
• 模态框操作后等待：关闭模态框后，在执行下一步操作前添加 notte page wait 500
• 检查遮罩层：如果点击无效，可能是模态框或遮罩层挡住了页面——使用屏幕截图进行确认

# Common pattern for handling unexpected modals
notte page press "Escape"
notte page wait 500
notte page click "#target-element"

查看无头会话

使用 --headless（默认值）运行，并不意味着你看不到浏览器：

• ViewerUrl：启动会话时，输出中会包含一个 ViewerUrl，在浏览器中打开即可实时观看会话
• Viewer 命令：notte sessions viewer 可直接打开查看器
• 非无头模式：只有在需要本地浏览器窗口时才使用 --headless=false（远程环境或 CI 环境不支持）

# Start headless session and get viewer URL
notte sessions start -o json | jq -r '.viewer_url'

# Or open viewer for current session
notte sessions viewer

机器人检测 / 隐身模式

如果你遇到拦截或看到 CAPTCHA，可以尝试启用我们的住宅代理：

notte sessions stop
notte sessions start --proxy

注意：使用不同参数启动新会话前，请务必停止当前会话。会话配置无法在会话运行期间更改。

其他资源

• 会话管理参考 - 详细的会话生命周期指南
• 函数管理参考 - 工作流自动化指南
• 账户管理参考 - Persona 和保险库指南

模板

可直接使用的 Shell 脚本模板：

• 表单自动化 - 填写并提交表单
• 已认证会话 - 使用凭据保险库登录
• 数据提取 - 抓取结构化数据