@rtrvr-ai/cli

Official rtrvr CLI for browser automation with cloud + extension routing.

Install

npm install -g @rtrvr-ai/cli
# or
npx @rtrvr-ai/cli --help

Requirements

• Node.js 18+

Quickstart

# Authenticate
rtrvr auth login

# Run an agent task
rtrvr run "Extract the top 10 products" --url https://example.com

# Scrape a page
rtrvr scrape --url https://example.com

# Check capabilities
rtrvr capabilities

# Diagnose connectivity
rtrvr doctor

Authentication

# OAuth bootstrap (interactive)
rtrvr auth login --oauth

# API key login
rtrvr auth login --api-key rtrvr_...

# Check auth status
rtrvr auth status

# Get raw token for automation
rtrvr auth token

# Logout (clear credentials)
rtrvr auth logout

Token types:

• rtrvr_... API keys can access cloud + MCP + control endpoints.
• mcp_at_... tokens are limited to MCP endpoints.

Google OAuth for Drive/Docs/Sheets:

# Check Google OAuth status
rtrvr auth google status

# Connect Google OAuth (opens browser)
rtrvr auth google login

# Use with --auth-token flag
rtrvr run "Extract data to Sheets" --url https://example.com --auth-token <google-token>

Environment variables override stored credentials:

export RTRVR_API_KEY=rtrvr_...
# or
export RTRVR_AUTH_TOKEN=rtrvr_...

Credential storage:

Credentials are stored in the OS keychain (macOS Keychain or Linux secret-service) when available, otherwise in ~/.config/rtrvr/config.json.

Login options:

rtrvr auth login --oauth                    # OAuth bootstrap
rtrvr auth login --api-key rtrvr_...        # Direct API key
rtrvr auth login --storage keychain         # Force keychain storage
rtrvr auth login --strict-auth              # Fail if OAuth unavailable
rtrvr auth login --no-browser               # Don't auto-open browser
rtrvr auth login --prefer-extension         # Set default target to extension

Core commands

rtrvr run "Do the task" --url https://example.com
rtrvr agent "Do the task" --url https://example.com
rtrvr scrape --url https://example.com
rtrvr extension "Run in local session" --url https://example.com
rtrvr devices list

Key flags for run / agent:

Input options:

• <input...> - positional task input
• --input <text> - task text (use - to read from stdin)
• --input-file <path> - read task from file
• -u, --url <url...> - starting URL(s)

Routing options:

• --target auto|cloud|extension - routing mode
• --cloud - shortcut for --target cloud
• --extension - shortcut for --target extension
• --device-id <id> - target extension device
• --prefer-extension - prefer extension in auto mode
• --require-local-session - require extension or fail

Data and schema:

• --schema-file <path> - JSON schema for structured output
• --file-url <url...> - file URL(s) for context

Configuration:

• --settings-json <json> - agent settings
• --tools-json <json> - tool configuration
• --options-json <json> - execution options
• --response-json <json> - response config (verbosity, inlineOutputMaxBytes)
• --webhooks-json <json> - webhook subscriptions array
• --auth-token <token> - Google OAuth access token for Drive/Docs/Sheets/Slides

Output options:

• --json - machine-readable JSON output
• --no-stream - disable SSE progress streaming
• --no-stream-output - hide tool output payloads in stream events

Scrape options:

All routing and output options above, plus:

• -u, --url <url...> - URL(s) to scrape (required)

Skills

rtrvr skills templates
rtrvr skills install-template agent-web
rtrvr skills add ./my-skill.md
rtrvr skills list
rtrvr skills apply my-skill "Find financing options" --url https://example.com

MCP helpers

rtrvr mcp init --client claude
rtrvr mcp init --client cursor
rtrvr mcp url

Raw MCP tools

rtrvr raw tool planner --params-json '{"user_input":"Summarize"}'
rtrvr raw act "Click login" --url https://example.com

Configuration

Config file: ~/.config/rtrvr/config.json

Available keys:

rtrvr config set defaultTarget cloud               # auto|cloud|extension
rtrvr config set preferExtensionByDefault true     # boolean
rtrvr config set authStorage keychain              # auto|keychain|config
rtrvr config set telemetryOptIn false              # boolean
rtrvr config set retryMaxAttempts 3                # number
rtrvr config set retryBaseDelayMs 250              # number (ms)
rtrvr config set retryMaxDelayMs 4000              # number (ms)
rtrvr config set cloudBaseUrl https://api.rtrvr.ai
rtrvr config set mcpBaseUrl https://mcp.rtrvr.ai
rtrvr config set controlBaseUrl https://cli.rtrvr.ai

Environment variable overrides:

• RTRVR_API_KEY or RTRVR_AUTH_TOKEN - auth token
• RTRVR_CONFIG_DIR - config directory path
• RTRVR_CLOUD_BASE_URL - cloud API base URL
• RTRVR_MCP_BASE_URL - MCP base URL
• RTRVR_CONTROL_BASE_URL - CLI control base URL

OAuth configuration:

rtrvr config set oauthPollIntervalMs 2000          # OAuth poll interval
rtrvr config set oauthTimeoutMs 300000             # OAuth timeout (5 min)