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

notte search <query>                                    # Search the web for a query
notte search <query> --depth fast|standard|deep         # Tune search depth (default: standard)
notte search <query> --output-type sourcedAnswer        # Get an LLM answer with sources

notte sessions list [--page N] [--page-size N] [--only-active]  # List 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

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
  --proxy                                  # Use default proxy rotation
  --proxy-country <code>                  # Proxy with specific country (e.g. us, gb, fr)
  --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)

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

notte agents list [--page N] [--page-size N] [--only-active] [--only-saved]  # List 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

notte functions list [--page N] [--page-size N] [--only-active]  # List functions
notte functions create --file workflow.py  # Create a new function
notte functions show                  # View current function details
notte functions show --function-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 [--page N] [--page-size N] [--only-active]  # 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

notte vaults list [--page N] [--page-size N] [--only-active]  # List all vaults
notte vaults create                                   # Create a new vault
notte vaults update --vault-id <id>                   # Update vault metadata
notte vaults delete --vault-id <id>                   # Delete a vault
notte vaults credentials list --vault-id <id>         # List all credentials
notte vaults credentials add --vault-id <id>          # Add credentials
notte vaults credentials get --vault-id <id>          # Get credentials for URL
notte vaults credentials delete --vault-id <id>       # Delete credentials

notte personas list [--page N] [--page-size N] [--only-active]  # List all personas
notte personas create                    # Create a new persona
notte personas show --persona-id <id>    # View persona details
notte personas delete --persona-id <id>  # Delete a persona
notte personas emails --persona-id <id>  # List emails
notte personas sms --persona-id <id>     # List SMS messages

notte profiles list [--page N] [--page-size N] [--name "..."]  # List all profiles
notte profiles create                    # Create a new profile
notte profiles show --profile-id <id>    # View profile details
notte profiles delete --profile-id <id>  # Delete a profile

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

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

$ 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

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

# 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

# List functions to find ID
notte functions list

# Run workflow
notte functions run --function-id func_abc123

# 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 --vault-id $VAULT_ID \
  --username "admin@example.com" \
  --password "$SECURE_PASSWORD" \
  --url "https://app.example.com"

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

# 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

# Get only active sessions (using built-in filter)
notte sessions list --only-active

# Paginate through results
notte sessions list --page 2 --page-size 5

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

### Tips

- **Viewing headless sessions**: When you start a session, the output includes a `ViewerUrl` - open it to watch your headless browser live
- **Element selectors**: If element IDs from `observe` (like `@B1`) don't work, use Playwright selectors: `#id`, `.class`, `button:has-text('Submit')`
- **Multiple matches**: Use `>> nth=0` suffix to select the first match: `button:has-text('OK') >> nth=0`
- **Closing modals**: `notte page press "Escape"` reliably dismisses most dialogs

### Skills Documentation

For comprehensive documentation including templates and reference guides, see the [notte-skills/plugins/notte-cli/skills/notte-browser](https://github.com/nottelabs/notte-cli/blob/HEAD/notte-skills/plugins/notte-cli/skills/notte-browser/SKILL.md) folder (vendored as a submodule from [nottelabs/notte-skills](https://github.com/nottelabs/notte-skills)).

## 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

```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)

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

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

notte completion powershell | Out-String | Invoke-Expression

make setup

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

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

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

# 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

notte sessions start --headless

npx skills add nottelabs/notte-skills