notte

Automa

Documentação

Notte CLI - Automação de navegador no seu terminal

Controle sessões de navegador e raspagem web através de comandos intuitivos baseados em recursos
→ Leia mais em: Landing • Console • Docs • X • LinkedIn

O que é o Notte CLI?

O Notte CLI traz todo o poder do notte.cc para o seu terminal — permitindo que você controle sessões de navegador e pipelines de raspagem web diretamente da linha de comando. Combine-o com scripts de shell, pipelines de CI/CD ou assistentes de codificação com IA para automação web repetível e scriptável.

Recursos

Sessões de navegador - Chromium/Chrome remoto com controle total
Arquivos - envie e baixe arquivos para o notte.cc
Formatos de saída - texto legível por humanos ou JSON para scripts
Personas - crie e gerencie identidades digitais com e-mail, telefone e SMS
Credenciais seguras - chaveiro do sistema para chaves de API, cofres para senhas de sites
Raspagem web - extração de dados estruturados com esquemas personalizados
Funções - agende e execute tarefas de automação repetíveis

Instalação

Homebrew

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

Instalação via Go

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

Compilar a partir do código-fonte

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

Início Rápido

1. Autentique-se

Especifique a chave de API usando um dos três métodos (verificados em ordem de prioridade):

# 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. Inicie uma Sessão de Navegador

notte sessions start

Assista à sessão ao vivo através do ViewerUrl na saída.

Comandos

Autenticação

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

Pesquisa na Web

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

A consulta pode ser entre aspas (notte search "what is anthropic") ou passada como palavras separadas (notte search what is anthropic). Use --output json para obter a resposta bruta da API para scripts.

Sessões de Navegador

notte sessions list [--page N] [--page-size N] [-a|--all]  # List running sessions (-a includes stopped)
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

Observação: Quando você inicia uma sessão, ela se torna automaticamente a sessão "atual". Todos os comandos subsequentes usam esta sessão por padrão. Use --session-id <session-id> somente quando precisar gerenciar várias sessões simultaneamente ou referenciar uma sessão específica.

Opções de Início de Sessão

notte sessions start \
  --browser-type chromium|chrome  # Browser type (default: chromium)
  --idle-timeout-minutes <minutes>        # Idle timeout (default: 3)
  --max-duration-minutes <minutes>        # Maximum session lifetime (default: 15)
  --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)
  --no-solve-captchas                     # Turn OFF captcha solving (on by default)
  --no-file-storage                       # Detach FileStorage (attached by default).
                                          # Disables page download and files --from session
  --advanced-stealth                      # Highest-fidelity browser for sites with
                                          # sophisticated bot detection (approved workspaces)
  --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
  --vault-id <id>                         # Vault used to resolve credential fields
  --screenshot-type <type>                # Screenshot type (raw, full, last_action)
  --chrome-args <args>                    # Chrome instance arguments (repeatable)

Ações de Página

Interaja com páginas usando comandos simplificados (requer uma sessão ativa). Inicie a sessão com --vault-id <id> antes de usar page fill --vault-field:

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 fill "#email" --vault-field email       # Fill from the session vault
notte page fill "#password" --vault-field password # Supports email, username, password, and mfa
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 <name>  # Fill a file input. <name> is a file in your
                                      # uploads store, not a local path - send it with
                                      # `notte files upload` first
notte page download <id>              # Download by clicking. The file lands in the
                                      # session store; retrieve it with
                                      # `notte files download <name> --from session`
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 page eval-js "document.title"   # Evaluate JavaScript in the page

Avaliando JavaScript

page eval-js imprime o valor avaliado sozinho no stdout — objetos e arrays como JSON, um null de JS como null — com a linha de status no stderr, para que capture e canalize sem pós-processamento:

title=$(notte page eval-js "document.title")

notte page eval-js "JSON.stringify([...document.querySelectorAll('a')].map(a => a.href))" | jq length

Retorne JSON.stringify(...) quando a resposta for estruturada. A saída de console.log é descartada — apenas o valor retornado volta. Um script com falha sai com código diferente de zero e relata o erro real de JavaScript; use -o json para obter o resultado completo da execução em vez do valor simples.

Funções

notte functions list [--page N] [--page-size N] [--include-deleted]  # 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] [--running]  # List runs for current function (--running = in-flight only)
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

Observação: Quando você cria uma função, ela se torna automaticamente a função "atual". Todos os comandos subsequentes usam esta função por padrão. Use --function-id <function-id> somente quando precisar gerenciar várias funções simultaneamente ou referenciar uma função específica.

Cofres

notte vaults list [--page N] [--page-size N] [--include-deleted]  # 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

Personas

notte personas list [--page N] [--page-size N] [--include-deleted]  # 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

Perfis

notte profiles list [--page N] [--page-size N] [--name "..."] [--include-deleted]  # 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

Arquivos

notte files upload <path>                                      # Upload a persistent input file
notte files list --from uploads                                # List persistent input files
notte files download <filename> --from uploads                 # Download a persistent input file
notte files list --from session [--session-id <id>]            # List files produced by a session
notte files download <filename> [--session-id <id>]            # Download a file produced by a session

Utilitários

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

Formatos de Saída

Texto

Tabelas legíveis por humanos com cores e formatação:

$ 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

Saída legível por máquina:

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

Os dados vão para o stdout, erros e progresso para o stderr para canalização limpa.

Exemplos

Pipeline Automatizado de Raspagem Web

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

# 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

Executando um Fluxo de Trabalho

# List functions to find ID
notte functions list

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

Gerenciando Credenciais com Segurança

# 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

Automação de Navegador em Múltiplas Etapas

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

# 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

Filtragem com JQ

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

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

Uso com Agentes de IA

Basta Perguntar ao Agente

A abordagem mais simples — basta dizer ao seu agente para usá-lo:

Use o notte para testar o fluxo de login. Execute notte --help para ver os comandos disponíveis.

A saída de --help é abrangente e a maioria dos agentes consegue descobrir a partir daí.

Assistentes de Codificação com IA

Adicione a habilidade ao seu assistente de codificação com IA para obter contexto mais rico:

npx skills add nottelabs/notte-skills

Isso funciona com Claude Code, Cursor, Windsurf e outros assistentes compatíveis com MCP.

AGENTS.md / CLAUDE.md

Para resultados mais consistentes, adicione ao seu arquivo de instruções do projeto ou global:

## 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 "@I1" "text"` - Interact using element IDs
5. `notte page scrape --instructions "..."` - Extract structured data
6. `notte sessions stop` - Clean up when done

Dicas

Visualizando sessões: Quando você inicia uma sessão, a saída inclui um ViewerUrl - abra-o para assistir ao navegador ao vivo
Duração da sessão: as sessões são encerradas após 3 minutos de inatividade ou 15 minutos no total por padrão. Aumente --idle-timeout-minutes/--max-duration-minutes para algo lento, ou o próximo comando falhará com Session closed
Seletores de elementos: Se os IDs de elementos do observe (como @B1) não funcionarem, use seletores do Playwright: #id, .class, button:has-text('Submit')
Múltiplas correspondências: Use o sufixo >> nth=0 para selecionar a primeira correspondência: button:has-text('OK') >> nth=0
Fechando modais: notte page press "Escape" dispensa de forma confiável a maioria dos diálogos

Documentação de Habilidades

Para documentação abrangente, incluindo modelos e guias de referência, consulte a pasta notte-skills/plugins/notte-cli/skills/notte-browser (fornecida como submódulo de nottelabs/notte-skills).

Segurança

Armazenamento de Credenciais

As chaves de API são armazenadas com segurança no chaveiro do seu sistema:

macOS: Acesso às Chaves (Keychain Access)
Linux: Secret Service (GNOME Keyring, KWallet)
Windows: Gerenciador de Credenciais

Boas Práticas

Nunca passe chaves de API na linha de comando
Use cofres para senhas de sites e cartões de pagamento
Rotacione as chaves de API regularmente pelo painel do notte.cc
Use notte auth logout para remover chaves armazenadas

Completions de Shell

Gere completions de shell para o seu shell preferido:

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

Desenvolvimento

Após clonar, instale os hooks do git:

make setup

Isso instala os hooks de pré-commit e pré-push do lefthook para linting e testes.

Licença

Este projeto é licenciado sob a Licença MIT.