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.
- 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
- Node.js: 20.0.0 or higher
- pnpm: 10.0.0 or higher (recommended) or npm
- Chrome/Chromium: Will be downloaded automatically
# 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# 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-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 URLTest 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:9222Launch browser and navigate to URL.
aironin-browse launch https://example.comClick at specified coordinates.
# Click at x=200, y=300
aironin-browse click 200,300Type text into the browser.
aironin-browse type "Hello World"Scroll the page up or down.
# Scroll down
aironin-browse scroll down
# Scroll up
aironin-browse scroll upHover at specified coordinates.
aironin-browse hover 200,300Resize browser window.
# Resize to 1200x800
aironin-browse resize 1200,800Close the browser.
aironin-browse closeStart interactive mode for manual testing.
aironin-browse interactiveYou 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:9222To connect to an existing Chrome instance:
-
Start Chrome with remote debugging:
chrome --remote-debugging-port=9222
-
The tool will automatically detect and connect to remote browsers:
aironin-browse launch https://example.com
-
Or force remote connection:
export REMOTE_BROWSER_ENABLED=true export REMOTE_BROWSER_HOST=http://localhost:9222 aironin-browse launch https://example.com
Interactive mode allows you to test commands manually:
aironin-browse interactiveAvailable commands in interactive mode:
help- Show available commandstest- Run connection testlaunch <url>- Launch browser and navigateclick <x,y>- Click at coordinatestype <text>- Type textscroll <up|down>- Scroll pagehover <x,y>- Hover at coordinatesresize <w,h>- Resize browser windowclose- Close browserexit- 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
-
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
-
Permission errors:
- Check file permissions for storage directory
- Ensure write access to current directory
-
Remote connection fails:
- Verify Chrome is running with
--remote-debugging-port=9222 - Check firewall settings
- Ensure correct host URL
- Verify Chrome is running with
Enable debug logging:
DEBUG=aironin-browse* aironin-browse launch https://example.com# Show all commands
aironin-browse --help
# Show help for specific command
aironin-browse launch --help# Install dependencies
pnpm install
# Build the project
pnpm build
# Run in development mode
pnpm dev
# Run tests
pnpm test
# Lint code
pnpm lintaironin-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
-
Add command to
src/cli.ts:program .command("mycommand") .description("My new command") .argument("<param>", "Parameter description") .action(async (param: string) => { // Command implementation });
-
Rebuild:
pnpm build
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();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
}- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- Submit a pull request
MIT License - see LICENSE file for details.
aiRonin Browse CLI is developed by CK @ iRonin.IT.
iRonin.IT is a software development company specializing in AI-powered tools and automation solutions.
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! π―