Skip to content

About

Browser automation CLI tool with headed Chrome support for LLM/AI agents

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

Β 

History

3 Commits

Folders and files

Repository files navigation

aiRonin Browse CLI

A command-line tool for browser automation with headed Chrome support - perfect for AI agents that need to see what they're doing in real-time.

🎯 Why This Tool?

  • AI Agent Optimized: Screenshot analysis and visual feedback for AI decision-making
  • Remote Browser Detection: Automatically finds and uses remote browsers when available
  • Headed Mode: Unlike headless automation, you can see the browser in action
  • Real-time Visibility: Watch AI agents interact with web pages
  • Better Debugging: Screenshots and console logs help debug issues
  • Smart Tab Management: Handles multiple tabs and domains intelligently
  • Network Monitoring: Automatically waits for page loads after interactions

πŸ“‹ Prerequisites

  • Node.js: 20.0.0 or higher
  • pnpm: 10.0.0 or higher (recommended) or npm
  • Chrome/Chromium: Will be downloaded automatically

πŸš€ Quick Start

Installation

# Clone the repository
git clone https://github.com/iRoninIT/aironin-browse-cli.git
cd aironin-browse-cli

# Install dependencies
pnpm install

# Build the tool
pnpm build

# Make it globally available (optional)
pnpm link

Basic Usage

# Test the browser automation
aironin-browse test

# Launch browser and navigate to a URL
aironin-browse launch https://example.com

# Click at coordinates
aironin-browse click 200,300

# Type text
aironin-browse type "Hello World"

# Scroll down
aironin-browse scroll down

# Close browser
aironin-browse close

πŸ“– Command Reference

Global Options

-v, --viewport <size>    Browser viewport size (e.g., 900x600)
-q, --quality <number>    Screenshot quality (1-100)
-r, --remote             Force remote browser connection (default: auto-detect)
-h, --host <url>         Remote browser host URL

Commands

test [options]

Test browser connection and functionality.

# Basic test
aironin-browse test

# Test with custom URL
aironin-browse test --url https://google.com

# Test with remote browser (auto-detection enabled by default)
aironin-browse test --remote --host http://localhost:9222

launch <url>

Launch browser and navigate to URL.

aironin-browse launch https://example.com

click <coordinates>

Click at specified coordinates.

# Click at x=200, y=300
aironin-browse click 200,300

type <text>

Type text into the browser.

aironin-browse type "Hello World"

scroll <direction>

Scroll the page up or down.

# Scroll down
aironin-browse scroll down

# Scroll up
aironin-browse scroll up

hover <coordinates>

Hover at specified coordinates.

aironin-browse hover 200,300

resize <size>

Resize browser window.

# Resize to 1200x800
aironin-browse resize 1200,800

close

Close the browser.

aironin-browse close

interactive

Start interactive mode for manual testing.

aironin-browse interactive

πŸ”§ Configuration

Environment Variables

You can configure the tool using environment variables:

# Browser viewport size
export BROWSER_VIEWPORT_SIZE=1200x800

# Screenshot quality (1-100)
export SCREENSHOT_QUALITY=85

# Enable remote browser connection
export REMOTE_BROWSER_ENABLED=true

# Remote browser host URL
export REMOTE_BROWSER_HOST=http://localhost:9222

Remote Browser Setup

To connect to an existing Chrome instance:

  1. Start Chrome with remote debugging:

    chrome --remote-debugging-port=9222
  2. The tool will automatically detect and connect to remote browsers:

    aironin-browse launch https://example.com
  3. Or force remote connection:

    export REMOTE_BROWSER_ENABLED=true
    export REMOTE_BROWSER_HOST=http://localhost:9222
    aironin-browse launch https://example.com

πŸ§ͺ Interactive Mode

Interactive mode allows you to test commands manually:

aironin-browse interactive

Available commands in interactive mode:

  • help - Show available commands
  • test - Run connection test
  • launch <url> - Launch browser and navigate
  • click <x,y> - Click at coordinates
  • type <text> - Type text
  • scroll <up|down> - Scroll page
  • hover <x,y> - Hover at coordinates
  • resize <w,h> - Resize browser window
  • close - Close browser
  • exit - Exit interactive mode

Example session:

aironin> test
aironin> launch https://example.com
aironin> click 200,300
aironin> type Hello World
aironin> scroll down
aironin> exit

πŸ” Troubleshooting

Common Issues

  1. Chrome not launching:

    • Ensure sufficient disk space for Chromium download
    • Check internet connection for Chromium download
    • Verify Chrome/Chromium is not already running in debug mode
  2. Permission errors:

    • Check file permissions for storage directory
    • Ensure write access to current directory
  3. Remote connection fails:

    • Verify Chrome is running with --remote-debugging-port=9222
    • Check firewall settings
    • Ensure correct host URL

Debug Mode

Enable debug logging:

DEBUG=aironin-browse* aironin-browse launch https://example.com

Getting Help

# Show all commands
aironin-browse --help

# Show help for specific command
aironin-browse launch --help

πŸ› οΈ Development

Building from Source

# Install dependencies
pnpm install

# Build the project
pnpm build

# Run in development mode
pnpm dev

# Run tests
pnpm test

# Lint code
pnpm lint

Project Structure

aironin-browse-cli/
β”œβ”€β”€ src/
β”‚   β”œβ”€β”€ cli.ts              # Main CLI entry point
β”‚   └── browser/
β”‚       β”œβ”€β”€ BrowserSession.ts    # Core browser automation
β”‚       └── browserDiscovery.ts  # Browser discovery utilities
β”œβ”€β”€ dist/                   # Built files
β”œβ”€β”€ package.json
└── tsconfig.json

Adding New Commands

  1. Add command to src/cli.ts:

    program
      .command("mycommand")
      .description("My new command")
      .argument("<param>", "Parameter description")
      .action(async (param: string) => {
        // Command implementation
      });
  2. Rebuild:

    pnpm build

πŸ“¦ API Reference

BrowserSession Class

The core browser automation class:

import { BrowserSession } from "./browser/BrowserSession.js";

const browser = new BrowserSession();

// Launch browser
await browser.launchBrowser();

// Navigate to URL
const result = await browser.navigateToUrl("https://example.com");

// Click at coordinates
await browser.click("200,300");

// Type text
await browser.type("Hello World");

// Scroll
await browser.scrollDown();
await browser.scrollUp();

// Close browser
await browser.closeBrowser();

Return Values

All actions return a BrowserActionResult:

interface BrowserActionResult {
  screenshot?: string; // Base64 encoded screenshot
  logs?: string; // Console logs
  currentUrl?: string; // Current page URL
  currentMousePosition?: string; // Last mouse position
}

🀝 Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Submit a pull request

πŸ“„ License

MIT License - see LICENSE file for details.

🏒 About

aiRonin Browse CLI is developed by CK @ iRonin.IT.

iRonin.IT is a software development company specializing in AI-powered tools and automation solutions.

πŸ†˜ Support

For issues and questions:

  • Open an issue on the repository
  • Check the troubleshooting section
  • Review the configuration options

Ready to automate browsers with full visibility! 🎯

About

Browser automation CLI tool with headed Chrome support for LLM/AI agents

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages