Notte CLI

Browser automation in your terminal.

Control browser sessions, AI agents, and web scraping through intuitive resource-based commands.

Features

AI agents - run and monitor AI-powered browser functions
Browser sessions - headless or headed Chrome/Firefox with full control
Files - upload and download files to notte.cc
Output formats - human-readable text or JSON for scripting
Personas - create and manage digital identities with email, phone, and SMS
Secure credentials - system keyring for API keys, vaults for website passwords
Web scraping - structured data extraction with custom schemas
Functions - schedule and execute repeatable automation tasks

Installation

Homebrew

brew tap nottelabs/notte-cli https://github.com/nottelabs/notte-cli.git
brew install notte

Go Install

go install github.com/nottelabs/notte-cli/cmd/notte@latest

Build from Source

git clone https://github.com/nottelabs/notte-cli.git
cd notte-cli
make build

Quick Start

1. Authenticate

Specify the API key using one of three methods (checked in priority order):

# 1. Via environment variable (recommended for CI/CD)
export NOTTE_API_KEY="your-api-key"
# 2. Via system keyring (recommended for local development)
notte auth login
# 3. Via config file (~/.notte/cli/config.json)
# create ~/.notte/cli/config.json and add your API key
notte auth status

2. Start a Browser Session

notte sessions start --headless

Commands

Authentication

notte auth login                     # Store API key in system keychain
notte auth logout                    # Remove API key from keychain
notte auth status                    # Show authentication status

Browser Sessions

notte sessions list                   # List all active sessions
notte sessions start [flags]          # Start a new session
notte sessions status                 # Get current session status
notte sessions stop                   # Stop current session
notte sessions cookies                # Get all cookies from current session
notte sessions cookies-set --file cookies.json  # Set cookies in current session
notte sessions network                # View network activity logs
notte sessions replay                 # Get session replay data
notte sessions workflow-code          # Export session steps as Python code
notte sessions viewer                 # Open session viewer in browser
notte sessions code                   # Get Python script for session steps

Note: When you start a session, it automatically becomes the "current" session. All subsequent commands use this session by default. Use --session-id <session-id> only when you need to manage multiple sessions simultaneously or reference a specific session.

Session Start Options

notte sessions start \
  --browser-type chromium|chrome|firefox  # Browser type (default: chromium)
  --headless                              # Run in headless mode (default: true)
  --idle-timeout-minutes <minutes>        # Idle timeout (closes after inactivity)
  --max-duration-minutes <minutes>        # Maximum session lifetime
  --user-agent <string>                   # Custom user agent
  --viewport-width <pixels>               # Viewport width
  --viewport-height <pixels>              # Viewport height
  --proxies                               # Use default proxy rotation
  --solve-captchas                        # Automatically solve captchas
  --use-file-storage                      # Enable file storage for downloads
  --cdp-url <url>                         # CDP URL of remote session provider
  --profile-id <id>                       # Profile ID to use for session
  --profile-persist                       # Save browser state to profile on close
  --screenshot-type <type>                # Screenshot type (raw, full, last_action)
  --chrome-args <args>                    # Chrome instance arguments (repeatable)

Page Actions

Interact with pages using simplified commands (requires an active session):

notte page observe                    # Get page state and available actions
notte page scrape --instructions "..." # Scrape content from the page 
notte page click B3                # Click an element by ID
notte page fill I1 "text"       # Fill an input field
notte page goto "https://example.com" # Navigate to a URL
notte page back                       # Go back in history
notte page forward                    # Go forward in history
notte page scroll-down [amount]       # Scroll down the page
notte page scroll-up [amount]         # Scroll up
notte page press "Enter"              # Press a key
notte page screenshot                 # Take a screenshot
notte page select <id> "option"       # Select dropdown option
notte page check <id>                 # Check/uncheck checkbox
notte page upload <id> <file>         # Upload a file
notte page download <id>              # Download file by clicking element
notte page new-tab <url>              # Open URL in new tab
notte page switch-tab <index>         # Switch to tab by index
notte page close-tab                  # Close current tab
notte page reload                     # Reload page
notte page wait <seconds>             # Wait for duration
notte page captcha-solve              # Solve captcha

AI Agents

notte agents list                     # List all AI agents
notte agents start --task "..."       # Start a new AI agent (auto-uses current session)
notte agents status                   # Get agent status (uses current agent)
notte agents stop                     # Stop an agent (uses current agent)
notte agents workflow-code            # Get agent's workflow code
notte agents replay                   # Get agent execution replay

Note: When you start an agent, it automatically becomes the "current" agent. All subsequent commands use this agent by default. Use --id <agent-id> only when you need to manage multiple agents. If a session is active, agents start will automatically use that session unless --session-id is specified.

Functions

notte functions list                  # List all functions
notte functions create --file workflow.py  # Create a new function
notte functions show                  # View current function details
notte functions show --id <id>        # View specific function details (different from current function)
notte functions update --file workflow.py  # Update current function code
notte functions delete                # Delete current function
notte functions fork                  # Fork current function to new version
notte functions run                   # Execute current function
notte functions runs                  # List runs for current function
notte functions run-stop --run-id <id>  # Stop a running function execution
notte functions run-metadata --run-id <id>  # Get run logs and results
notte functions schedule --cron "0 9 * * *"  # Schedule current function
notte functions unschedule            # Remove schedule from current function

Note: When you create a function, it automatically becomes the "current" function. All subsequent commands use this function by default. Use --id <function-id> only when you need to manage multiple functions simultaneously or reference a specific function.

Vaults

notte vaults list                               # List all vaults
notte vaults create                             # Create a new vault
notte vaults update --id <id>                   # Update vault metadata
notte vaults delete --id <id>                   # Delete a vault
notte vaults credentials list --id <id>         # List all credentials
notte vaults credentials add --id <id>          # Add credentials
notte vaults credentials get --id <id>          # Get credentials for URL
notte vaults credentials delete --id <id>       # Delete credentials

Personas

notte personas list                   # List all personas
notte personas create                 # Create a new persona
notte personas show --id <id>         # View persona details
notte personas delete --id <id>       # Delete a persona
notte personas emails --id <id>       # Manage email addresses
notte personas sms --id <id>          # Manage SMS numbers
notte personas phone --id <id>        # Manage phone numbers

Profiles

notte profiles list                   # List all profiles
notte profiles create                 # Create a new profile
notte profiles show --id <id>         # View profile details
notte profiles delete --id <id>       # Delete a profile

Files

notte files list                     # List uploaded files
notte files upload <path>            # Upload a file
notte files download <id>            # Download a file by ID

Utilities

notte usage                          # View API usage statistics
notte health                         # Check API health status
notte version                        # Show CLI version

Output Formats

Text

Human-readable tables with colors and formatting:

$ notte sessions list
ID                        STATUS    BROWSER     CREATED
ses_abc123def456          ACTIVE    chromium    2024-01-15 10:30:00
ses_xyz789uvw012          STOPPED   chrome      2024-01-15 09:15:00

JSON

Machine-readable output:

$ notte sessions list --output json
{
  "sessions": [
    {
      "id": "ses_abc123def456",
      "status": "ACTIVE",
      "browser": "chromium",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

Data goes to stdout, errors and progress to stderr for clean piping.

Examples

Automated Web Scraping Pipeline

# Start session (automatically becomes the current session)
notte sessions start --headless

# Navigate to page
notte page goto "https://news.ycombinator.com"

# Extract structured data
notte page scrape --instructions "Extract top 10 stories with title and URL"

# Cleanup
notte sessions stop

Running a Workflow

# List functions to find ID
notte functions list

# Run workflow
notte functions run --id func_abc123

Managing Credentials Securely

# Create a vault for production credentials
VAULT_ID=$(notte vaults create --name "Production Sites" -o json | jq -r '.id')

# Add website credentials
notte vaults credentials add --id $VAULT_ID \
  --username "admin@example.com" \
  --password "$SECURE_PASSWORD" \
  --url "https://app.example.com"

# List stored credentials
notte vaults credentials list --id $VAULT_ID

Multi-Step Browser Automation

# Start browser with specific configuration
notte sessions start \
  --browser-type chrome \
  --viewport-width 1920 \
  --viewport-height 1080 \
  --solve-captchas

# Navigate and interact
notte page goto "https://example.com"
notte page click "#login-button"
notte page fill "#username" "user@example.com"

# Get current page state with available actions
notte page observe

# Stop when done
notte sessions stop

JQ Filtering

# Get only active sessions
notte sessions list --output json | jq '.sessions[] | select(.status=="ACTIVE")'

# Extract session IDs
notte sessions list --output json | jq -r '.sessions[].id'

Usage with AI Agents

Just Ask the Agent

The simplest approach - just tell your agent to use it:

Use notte to test the login flow. Run notte --help to see available commands.

The --help output is comprehensive and most agents can figure it out from there.

AI Coding Assistants

Add the skill to your AI coding assistant for richer context:

npx skills add nottelabs/notte-cli

This works with Claude Code, Cursor, Windsurf, and other MCP-compatible assistants.

AGENTS.md / CLAUDE.md

For more consistent results, add to your project or global instructions file:

## Browser Automation

Use `notte` for web automation. Run `notte --help` for all commands.

Core workflow:
1. `notte sessions start` - Start a browser session
2. `notte page goto <url>` - Navigate to a URL
3. `notte page observe` - Get interactive elements with IDs (B1, B2)
4. `notte page click B1` / `notte page fill B2 "text"` - Interact using element IDs
5. `notte page scrape --instructions "..."` - Extract structured data
6. `notte sessions stop` - Clean up when done

Skills Documentation

For comprehensive documentation including templates and reference guides, see the skills/notte-browser folder.

Security

Credential Storage

API keys are stored securely in your system's keychain:

macOS: Keychain Access
Linux: Secret Service (GNOME Keyring, KWallet)
Windows: Credential Manager

Best Practices

Never pass API keys on the command line
Use vaults for website passwords and payment cards
Rotate API keys regularly from notte.cc dashboard
Use notte auth logout to remove stored keys

Shell Completions

Generate shell completions for your preferred shell:

Bash

# macOS (Homebrew):
notte completion bash > $(brew --prefix)/etc/bash_completion.d/notte

# Linux:
notte completion bash > /etc/bash_completion.d/notte

# Or source directly:
source <(notte completion bash)

Zsh

notte completion zsh > "${fpath[1]}/_notte"

Fish

notte completion fish > ~/.config/fish/completions/notte.fish

PowerShell

notte completion powershell | Out-String | Invoke-Expression

Development

After cloning, install git hooks:

make setup

This installs lefthook pre-commit and pre-push hooks for linting and testing.

License

MIT

Links

Notte API Documentation

Name		Name	Last commit message	Last commit date
Latest commit History 136 Commits
.github		.github
Formula		Formula
cmd/notte		cmd/notte
internal		internal
scripts		scripts
skills/notte-browser		skills/notte-browser
tests/integration		tests/integration
.env.example		.env.example
.gitignore		.gitignore
.golangci.yml		.golangci.yml
.goreleaser.yaml		.goreleaser.yaml
.lefthook.yml		.lefthook.yml
.pre-commit-config.yaml		.pre-commit-config.yaml
Makefile		Makefile
README.md		README.md
go.mod		go.mod
go.sum		go.sum
lefthook.yml		lefthook.yml

nottelabs/notte-cli

Folders and files

Latest commit

History

Repository files navigation