browser-automation-cli 0.1.0__tar.gz

browser_automation_cli-0.1.0/AGENTS.md

@@ -0,0 +1,155 @@
+# Agent Setup Guide
+
+> **For agent integration, see [SKILL.md](./SKILL.md) for usage patterns. Add the SKILL.md to your local setup as part of your skills configuration.**
+
+This document explains how to set up Browser CLI for users and integrate it into your agent workflow.
+
+## Setup (One-time)
+
+Preferred setup (published package):
+
+```bash
+pipx install browser-cli
+
+# If "command not found" after install:
+# export PATH="$HOME/.local/bin:$PATH"
+
+browser install
+```
+
+If package is not published yet (install from Git):
+
+```bash
+pipx install "git+https://github.com/<your-org>/<your-repo>.git"
+browser install
+```
+
+From local checkout (developer path):
+
+```bash
+bash ./setup.sh
+```
+
+## Starting the Daemon
+
+The daemon must be running before any browser actions work. Start it with:
+
+```bash
+browser-daemon
+```
+
+**Important:** The daemon opens a visible browser window. It must remain running.
+
+## Session Lifecycle
+
+1. **Create session** - User manually logs into sites:
+   ```bash
+   browser create
+   ```
+
+2. **Use session** - Agent performs actions:
+   ```bash
+   browser <session_id> navigate github.com/user/repo
+   browser <session_id> snapshot
+   ```
+
+3. **Share session** - Multiple agents can use the same session ID
+
+4. **Delete when done**:
+   ```bash
+   browser delete <session_id>
+   ```
+
+## Agent Workflow Example
+
+```bash
+# 1. Create session, user logs in manually
+browser create
+# → returns session_id like "abc12345"
+
+# 2. Navigate and inspect
+browser abc12345 navigate github.com/user/repo
+browser abc12345 snapshot
+# → returns elements array
+
+# 3. Interact
+browser abc12345 click "button.submit"
+browser abc12345 type "input[name=message]" "Hello"
+browser abc12345 screenshot
+
+# 4. Agent parses JSON output to decide next steps
+```
+
+## Output Format
+
+All actions return JSON:
+```json
+{
+  "success": true,
+  "url": "https://github.com/user/repo",
+  "title": "Repository"
+}
+```
+
+For `snapshot`:
+```json
+{
+  "success": true,
+  "elements": [
+    {"ref": "el_0", "tag": "a", "text": "README", "href": "..."},
+    {"ref": "el_1", "tag": "button", "text": "Submit", "name": null}
+  ]
+}
+```
+
+For `screenshot`:
+```json
+{
+  "success": true,
+  "image": "base64encodedstring..."
+}
+```
+
+## Shell Integration
+
+Agents can call the CLI via subprocess. Example patterns:
+
+```python
+import subprocess
+import json
+
+result = subprocess.run(
+    ["browser", "abc12345", "snapshot"],
+    capture_output=True,
+    text=True
+)
+data = json.loads(result.stdout)
+```
+
+```typescript
+import { execSync } from 'child_process';
+
+const output = execSync(`browser abc12345 snapshot`);
+const data = JSON.parse(output.toString());
+```
+
+## Sharing Sessions Between Agents
+
+Sessions persist until explicitly deleted. Multiple agents can reference the same session:
+
+```bash
+# Agent A creates session
+browser create
+# → abc12345
+
+# Agent B uses same session
+browser abc12345 navigate github.com
+```
+
+## Key Points
+
+- Daemon runs once, handles multiple sessions
+- User manually authenticates (no credentials in code)
+- Session IDs are 8-character hex strings
+- Browser window stays open for the session duration
+- Actions are blocking (not parallel within a session)

browser_automation_cli-0.1.0/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Browser CLI Maintainers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

browser_automation_cli-0.1.0/Makefile

@@ -0,0 +1,22 @@
+.PHONY: install daemon cli help
+
+help:
+	@echo "Browser CLI - Usage"
+	@echo ""
+	@echo "  make install          Install dependencies and commands"
+	@echo "  make daemon          Start the browser daemon (background)"
+	@echo "  browser create       Create new session"
+	@echo "  browser list         List sessions"
+	@echo "  browser <id> <cmd>   Run command on session"
+
+install:
+	@pip install playwright
+	@playwright install chromium
+	@pip install -e .
+
+daemon:
+	@browser-daemon
+
+start-daemon:
+	@browser-daemon &
+	@echo "Daemon started in background"

browser_automation_cli-0.1.0/PKG-INFO

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: browser-automation-cli
+Version: 0.1.0
+Summary: Lightweight browser automation daemon with CLI
+Project-URL: Homepage, https://github.com/<your-org>/<your-repo>
+Project-URL: Repository, https://github.com/<your-org>/<your-repo>
+Author: Browser CLI Maintainers
+License: MIT License
+        
+        Copyright (c) 2026 Browser CLI Maintainers
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE.txt
+Keywords: agent,automation,browser,cli,playwright
+Requires-Python: >=3.10
+Requires-Dist: playwright>=1.40.0
+Description-Content-Type: text/markdown
+
+# Browser CLI
+
+> **If you are an LLM, see [AGENTS.md](./AGENTS.md) for quick setup instructions.**
+
+---
+
+## If you are a human
+
+### Install
+
+Preferred (published package):
+
+```bash
+pipx install browser-cli
+browser install
+```
+
+Without publishing (install directly from Git):
+
+```bash
+pipx install "git+https://github.com/<your-org>/<your-repo>.git"
+browser install
+```
+
+From a local checkout:
+
+```bash
+bash ./setup.sh
+```
+
+Manual dev install (fallback):
+
+```bash
+pip install -e .
+browser install
+```
+
+### Start the daemon
+
+In a terminal:
+
+```bash
+browser-daemon
+```
+
+A browser window will open. Keep this running.
+
+### Create a session
+
+In another terminal:
+
+```bash
+browser create
+```
+
+This opens a fresh browser window. Manually log into any sites you need (GitHub, Jira, etc.).
+
+### Run browser actions
+
+```bash
+# Navigate to a site
+browser <session_id> navigate github.com/user/repo
+
+# Get page elements
+browser <session_id> snapshot
+
+# Click an element
+browser <session_id> click ".readme"
+
+# Take a screenshot
+browser <session_id> screenshot
+
+# Type text
+browser <session_id> type "input[name=search]" "query"
+```
+
+### List active sessions
+
+```bash
+browser list
+```
+
+### Delete a session
+
+```bash
+browser delete <session_id>
+```
+
+### Stop the daemon
+
+Press `Ctrl+C` in the terminal running `browser-daemon`.
+
+---
+
+## Commands Reference
+
+### Standalone (No Daemon)
+
+**Capture Command:**
+
+Uses JPEG format for efficient file sizes (~10x smaller than PNG).
+
+```bash
+browser capture <url> [options]
+```
+
+**Options:**
+- `-f, --full-page` - Capture full scrollable page (default: viewport only)
+- `-o, --output <path>` - Custom output path
+
+**Examples:**
+```bash
+# Quick viewport screenshot (fastest, smallest file)
+browser capture https://example.com
+
+# Full page screenshot
+browser capture https://example.com -f
+
+# Save to custom location
+browser capture https://example.com -o ./my-screenshot.jpg
+
+# Full page + custom path
+browser capture https://example.com -f -o ./full-page.jpg
+
+# Capture localhost
+browser capture http://localhost:3000
+browser capture http://127.0.0.1:8080/dashboard
+```
+
+### Daemon Commands
+
+| Command | Description |
+|---------|-------------|
+| `browser install` | Install Chromium runtime |
+| `browser create` | Create new session (opens browser for login) |
+| `browser list` | List active sessions |
+| `browser <id> navigate <url>` | Navigate to URL |
+| `browser <id> snapshot [selector]` | Get page elements |
+| `browser <id> click <selector>` | Click element |
+| `browser <id> type <selector> <text>` | Type text |
+| `browser <id> hover <selector>` | Hover element |
+| `browser <id> select <selector> <value>` | Select dropdown option |
+| `browser <id> press <key>` | Press keyboard key |
+| `browser <id> screenshot [selector]` | Take screenshot |
+| `browser <id> back` | Go back |
+| `browser <id> forward` | Go forward |
+| `browser <id> delete` | Delete session |
+
+## Troubleshooting
+
+**"Command not found: browser" or "browser: command not found"**
+
+If `pipx install` succeeded but commands aren't found, your shell may not have `~/.local/bin` in PATH:
+
+```bash
+# Quick fix (current session only)
+export PATH="$HOME/.local/bin:$PATH"
+
+# Permanent fix (add to shell config)
+echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc  # or ~/.bashrc
+source ~/.zshrc  # apply immediately
+```
+
+**"Daemon not running"**
+```bash
+browser-daemon
+```
+
+**Browser doesn't open**
+```bash
+browser install
+```
+
+**Session not found**
+```bash
+browser list
+```

browser_automation_cli-0.1.0/README.md

@@ -0,0 +1,177 @@
+# Browser CLI
+
+> **If you are an LLM, see [AGENTS.md](./AGENTS.md) for quick setup instructions.**
+
+---
+
+## If you are a human
+
+### Install
+
+Preferred (published package):
+
+```bash
+pipx install browser-cli
+browser install
+```
+
+Without publishing (install directly from Git):
+
+```bash
+pipx install "git+https://github.com/<your-org>/<your-repo>.git"
+browser install
+```
+
+From a local checkout:
+
+```bash
+bash ./setup.sh
+```
+
+Manual dev install (fallback):
+
+```bash
+pip install -e .
+browser install
+```
+
+### Start the daemon
+
+In a terminal:
+
+```bash
+browser-daemon
+```
+
+A browser window will open. Keep this running.
+
+### Create a session
+
+In another terminal:
+
+```bash
+browser create
+```
+
+This opens a fresh browser window. Manually log into any sites you need (GitHub, Jira, etc.).
+
+### Run browser actions
+
+```bash
+# Navigate to a site
+browser <session_id> navigate github.com/user/repo
+
+# Get page elements
+browser <session_id> snapshot
+
+# Click an element
+browser <session_id> click ".readme"
+
+# Take a screenshot
+browser <session_id> screenshot
+
+# Type text
+browser <session_id> type "input[name=search]" "query"
+```
+
+### List active sessions
+
+```bash
+browser list
+```
+
+### Delete a session
+
+```bash
+browser delete <session_id>
+```
+
+### Stop the daemon
+
+Press `Ctrl+C` in the terminal running `browser-daemon`.
+
+---
+
+## Commands Reference
+
+### Standalone (No Daemon)
+
+**Capture Command:**
+
+Uses JPEG format for efficient file sizes (~10x smaller than PNG).
+
+```bash
+browser capture <url> [options]
+```
+
+**Options:**
+- `-f, --full-page` - Capture full scrollable page (default: viewport only)
+- `-o, --output <path>` - Custom output path
+
+**Examples:**
+```bash
+# Quick viewport screenshot (fastest, smallest file)
+browser capture https://example.com
+
+# Full page screenshot
+browser capture https://example.com -f
+
+# Save to custom location
+browser capture https://example.com -o ./my-screenshot.jpg
+
+# Full page + custom path
+browser capture https://example.com -f -o ./full-page.jpg
+
+# Capture localhost
+browser capture http://localhost:3000
+browser capture http://127.0.0.1:8080/dashboard
+```
+
+### Daemon Commands
+
+| Command | Description |
+|---------|-------------|
+| `browser install` | Install Chromium runtime |
+| `browser create` | Create new session (opens browser for login) |
+| `browser list` | List active sessions |
+| `browser <id> navigate <url>` | Navigate to URL |
+| `browser <id> snapshot [selector]` | Get page elements |
+| `browser <id> click <selector>` | Click element |
+| `browser <id> type <selector> <text>` | Type text |
+| `browser <id> hover <selector>` | Hover element |
+| `browser <id> select <selector> <value>` | Select dropdown option |
+| `browser <id> press <key>` | Press keyboard key |
+| `browser <id> screenshot [selector]` | Take screenshot |
+| `browser <id> back` | Go back |
+| `browser <id> forward` | Go forward |
+| `browser <id> delete` | Delete session |
+
+## Troubleshooting
+
+**"Command not found: browser" or "browser: command not found"**
+
+If `pipx install` succeeded but commands aren't found, your shell may not have `~/.local/bin` in PATH:
+
+```bash
+# Quick fix (current session only)
+export PATH="$HOME/.local/bin:$PATH"
+
+# Permanent fix (add to shell config)
+echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc  # or ~/.bashrc
+source ~/.zshrc  # apply immediately
+```
+
+**"Daemon not running"**
+```bash
+browser-daemon
+```
+
+**Browser doesn't open**
+```bash
+browser install
+```
+
+**Session not found**
+```bash
+browser list
+```