<!--
hoody-browser Subskill (cli)
Auto-generated by Hoody Skills Generator
Generated: 2026-06-19T22:48:50.007Z
Model: mimo-v2.5-pro + fixer:mimo-v2.5-pro
Mode: cli


Tokens: 8037

DO NOT EDIT MANUALLY - Changes will be overwritten on next generation
-->

# hoody-browser Subskill

## Overview

### What is hoody-browser?
Browser automation service that provides headless Chrome capabilities via HTTP. Runs as a containerized service within the Hoody ecosystem, exposing browser operations through a REST API and CLI interface. Enables programmatic web interaction, content extraction, and automation without direct browser management.

### When to use it
- Web scraping and data extraction
- Automated testing of web applications
- Taking screenshots or generating PDFs of web pages
- Form submission and authentication flows
- Content monitoring and change detection
- JavaScript execution in browser context

### Philosophy
Follows Hoody's "accessible infrastructure" philosophy by wrapping complex browser automation into simple HTTP endpoints. Each browser instance runs isolated in a container, providing:
- Zero-config browser automation
- Predictable, stateless API interactions
- Built-in authentication and routing via Hoody Proxy
- Resource isolation between automation tasks

## Common Workflows

### Basic Browser Lifecycle

```
# 1. Start a browser instance
hoody browser start -c my-container -o json

# 2. Verify instance is running
hoody browser health -c my-container -o json

# 3. Get instance metadata
hoody browser info -c my-container -o json

# 4. Stop when done
hoody browser stop -c my-container
```

### Web Navigation & Content Extraction

```
# Navigate to a URL (opens new tab)
hoody browser navigate --url "https://example.com" -c my-container -o json

# Get page title using JavaScript evaluation
hoody browser eval --script "document.title" -c my-container -o json

# Extract visible text content
hoody browser text -c my-container -o json

# Get full HTML content
hoody browser html -c my-container -o json

# Capture screenshot (binary output)
hoody browser screenshot -c my-container
```

### Multi-Tab Management

```
# List all open tabs
hoody browser list -c my-container -o json

# Close specific tab by ID
hoody browser close --tab-id "tab_123" -c my-container

# Close active tab
hoody browser close -c my-container

# Shutdown entire browser instance
hoody browser shutdown -c my-container
```

### JavaScript Execution Patterns

```
# Execute simple expression
hoody browser eval --script "1 + 2" -c my-container -o json

# Interact with page elements
hoody browser eval --script "document.querySelector('button').click()" -c my-container -o json

# Extract data from page
hoody browser eval --script "Array.from(document.querySelectorAll('h1')).map(el => el.textContent)" -c my-container -o json

# Wait for element then interact
hoody browser eval --script "
  new Promise(resolve => {
    const check = setInterval(() => {
      if (document.querySelector('.loaded')) {
        clearInterval(check);
        resolve('Ready');
      }
    }, 100);
  })
" -c my-container -o json
```

### Cookie Management

```
# Get all cookies
hoody browser get -c my-container -o json

# Set a specific cookie
hoody browser set --cookies '[{"name":"session","value":"abc123","url":"https://example.com"}]' -c my-container

# Clear all cookies
hoody browser clear -c my-container
```

## Advanced Operations

### Authentication Flow Workflow

```
# 1. Start fresh browser
hoody browser start -c auth-flow -o json

# 2. Navigate to login page
hoody browser navigate --url "https://app.example.com/login" -c auth-flow -o json

# 3. Fill credentials
hoody browser eval --script "
  document.querySelector('#email').value = 'user@example.com';
  document.querySelector('#password').value = 'securepass';
  document.querySelector('button[type=submit]').click();
" -c auth-flow -o json

# 4. Wait for navigation
hoody browser eval --script "await new Promise(r => setTimeout(r, 2000))" -c auth-flow

# 5. Verify authentication
hoody browser eval --script "document.querySelector('.user-menu') !== null" -c auth-flow -o json

# 6. Get authenticated cookies
hoody browser get -c auth-flow -o json
```

### Multi-Page Scraping Pipeline

```
# Define scraping function
scrape_page() {
  local url=$1
  hoody browser navigate --url "$url" -c scraper -o json
  
  # Extract structured data
  hoody browser eval --script "
    const items = [];
    document.querySelectorAll('.product').forEach(item => {
      items.push({
        name: item.querySelector('.title').textContent,
        price: item.querySelector('.price').textContent,
        link: item.querySelector('a').href
      });
    });
    JSON.stringify(items);
  " -c scraper -o json
}

# Use in loop
hoody browser start -c scraper -o json
for page in 1 2 3; do
  scrape_page "https://shop.example.com/page/$page"
done
hoody browser shutdown -c scraper
```

### Error Recovery Patterns

```
# Check browser health before operations
if ! hoody browser health -c my-container -o json | grep -q '"status":"healthy"'; then
  echo "Browser unhealthy, restarting..."
  hoody browser restart -c my-container -o json
fi

# Retry with timeout detection
max_retries=3
for attempt in $(seq 1 $max_retries); do
  if hoody browser eval --script "document.readyState" -c my-container -o json | grep -q "complete"; then
    break
  fi
  
  if [ $attempt -eq $max_retries ]; then
    echo "Page load timeout after $max_retries attempts"
    exit 1
  fi
  
  sleep 2
done
```

### Performance Optimization

```
# Disable images for faster loading
hoody browser eval --script "
  document.querySelectorAll('img').forEach(img => {
    img.loading = 'lazy';
    img.decoding = 'async';
  });
" -c my-container

# Clear memory-intensive logs
hoody browser console --clear -c my-container
hoody browser network --clear -c my-container

# Use PDF generation for print-ready content
hoody browser pdf --format A4 --landscape -c my-container -o output.pdf

# Generate PDF with custom margins
hoody browser pdf --margin-top 20mm --margin-bottom 20mm -c my-container -o document.pdf
```

### Complex Workflow: Form Submission with Validation

```
# 1. Navigate to form
hoody browser navigate --url "https://form.example.com/apply" -c forms -o json

# 2. Fill all fields with validation
hoody browser eval --script "
  const form = document.querySelector('#application');
  form.querySelector('#name').value = 'John Doe';
  form.querySelector('#email').value = 'john@example.com';
  
  // Trigger validation
  form.querySelector('#email').dispatchEvent(new Event('blur'));
  
  // Check for validation errors
  const errors = document.querySelectorAll('.error-message');
  if (errors.length > 0) {
    return JSON.stringify({
      success: false,
      errors: Array.from(errors).map(e => e.textContent)
    });
  }
  
  return JSON.stringify({ success: true });
" -c forms -o json

# 3. Submit if validation passes
hoody browser eval --script "
  if (document.querySelectorAll('.error-message').length === 0) {
    document.querySelector('#application').submit();
    return 'submitted';
  }
  return 'validation_failed';
" -c forms -o json
```

## Quick Reference

### Essential Commands

| Command | Purpose | Example |
|---------|---------|---------|
| `hoody browser start` | Create/retrieve browser | `hoody browser start -c my-container` |
| `hoody browser navigate` | Go to URL | `hoody browser navigate --url "https://example.com" -c my-container` |
| `hoody browser eval` | Run JavaScript | `hoody browser eval --script "document.title" -c my-container` |
| `hoody browser screenshot` | Capture image | `hoody browser screenshot -c my-container` |
| `hoody browser text` | Get visible text | `hoody browser text -c my-container` |
| `hoody browser health` | Check service status | `hoody browser health -c my-container -o json` |
| `hoody browser list` | View open tabs | `hoody browser list -c my-container -o json` |
| `hoody browser shutdown` | Stop browser | `hoody browser shutdown -c my-container` |

### Required Parameters
- **Container ID**: Always specify with `-c <container-id>`
- **JSON Output**: Use `-o json` for machine-readable responses
- **URL**: Required for `navigate` and `navigate-post` commands
- **Script**: Required for `eval` and `eval-post` commands

### Common Response Format
```
{
  "status": "success",
  "data": {},
  "timestamp": "2024-01-01T12:00:00Z"
}
```

### Essential Flags
- `--url`: Target URL for navigation
- `--script`: JavaScript code to execute
- `--cookies`: JSON array of cookie objects
- `--tab-id`: Specific tab identifier
- `--clear`: Clear console/network logs (used with `console`/`network` commands)

### Workflow Pattern
1. **Start** browser instance
2. **Navigate** to target page
3. **Execute** JavaScript for interaction
4. **Extract** needed data
5. **Clean up** resources