@oya-ai/cli

Manage, navigate, benchmark, and watch browser agent instances on Oya Cloud, Browserbase, Steel, Anchor, Browser Use, or your self-hosted Chrome fleet straight from your terminal.

Oya does for browser vendors what OpenRouter does for LLM providers: one interface, and the vendor behind it is a setting.

npm install -g @oya-ai/cli

⚡ 60-Second Setup

# 1. Authenticate with an API key (interactive or via flags)
oya login

# 2. Interactive onboarding: pick your AI model, default browser provider, and solver
oya init

🚀 Everyday Workflow

# Start an orchestrated browser with an automatically rotated persona
oya start --persona auto
# Output: ✅ oya-8ed39f1c

# Navigate to a target website (defaults to your newest active browser)
oya goto https://news.ycombinator.com

# Drive the browser in plain English using your configured LLM
oya ask "Extract top 3 articles with points and comments"

# Open the sub-second interactive live stream in your desktop browser
oya open

# Check real-time health, command logs, and latencies
oya status

# Inspect running fleet instances
oya ls

# Gracefully terminate all active browsers
oya rm --all

Scripting: --json and exit codes

• --json puts exactly one JSON document on stdout. Prompts and progress go to stderr.
• A failure prints one line on stderr (✗ message, then a hint), or with --json one object: {"error", "code", "status"}.
• Exit codes: 0 done, 1 the request failed or got no answer, 2 the command could not be run as typed and nothing was sent.
• An unknown flag is an error, not ignored. --flag=value works as well as --flag value.
• --debug (or OYA_DEBUG=1) adds the status, the response body and the stack to a failure.
• oya install, oya init and oya stealth-test are for people and refuse --json.

📖 Command Reference

Fleet Execution & Control

| Command | Flags | Description | | :------------------- | :------------------------------------------------------------------------------------- | :-------------------------------------------------------- | | oya start | [--persona <id\|auto>] [--provider <p>] [--name <n>] [--governed] [--budget-usd <n>] | Launch browser instance and print its ID and CDP endpoint | | oya goto <url> | [--id <id>] | Navigate to URL (defaults to newest browser) | | oya ask "<prompt>" | [--id <id>] | Drive page using configured AI model | | oya open | [--id <id>] | Launch interactive SSE live view in system browser | | oya ls | [--json] | List active fleet browsers with health status | | oya status | [--id <id>] [--json] | Detailed metrics, error counts, and recent activity log | | oya rm <id>... | [--all] | Terminate target browser or entire fleet |

Persona Management (Anti-Ban Identities)

# List all saved personas and active concurrency
oya personas

# Create a new persona with fixed device parameters
oya personas new us-shopper --platform MacIntel --tz America/New_York --locale en-US --max 2 --geo US

# Preview generated hardware fingerprint without saving
oya personas new --preview --platform Win32 --tz Europe/London

# Clone an existing persona (same hardware fingerprint class, clean cookie jar)
oya personas clone <id> --name us-shopper-backup

# Edit persona concurrency cap or residential proxy geo
oya personas edit <id> --max 4 --geo US

# Delete a persona and its stored cookie jar
oya personas rm <id>

Moving logins (oya cookies)

A persona's cookie jar is its logins. Sign in once, then carry the session to wherever it is needed:

# Save a persona's logins to a file (owner-readable only: it holds live sessions)
oya cookies export <persona> --out logins.json

# The same, shaped for Playwright's context.addCookies()
oya cookies export <persona> --format playwright --out pw-cookies.json

# Bring logins in from a file: an export, or any JSON list of cookies
oya cookies import <persona> logins.json

# Give one persona another persona's logins (each keeps its own device)
oya cookies copy <from-persona> <to-persona>

Human-in-the-Loop Takeover

When automation encounters hardware 2FA, phone biometric approvals, or complex verification:

# 1. Acquire human control lease (pauses agent execution safely)
oya takeover <browser-id>

# 2. Complete manual verification via interactive live view
oya open --id <browser-id>

# 3. Release control when done
oya release <browser-id>

# 4. Acknowledge and resume autonomous agent execution
oya resume <browser-id>

Governance, Auditing & Webhooks

# View fleet overview, spend rate cards, and limits
oya control

# Inspect durable sessions (including cleanup-pending or disconnected nodes)
oya sessions [id]

# Force termination of an unresponsive session
oya stop <id> --force

# Read durable append-only lifecycle events
oya events [--after <cursor>]

# Audit hourly token and sandbox spend
oya usage

# Mint scoped service credentials
oya credential new --role operator --label "ci-runner"

# Register an HMAC-signed webhook for fleet lifecycle events
oya webhook new https://api.mycorp.com/oya-events

Stealth Benchmarking

Benchmark your browser deployment against live detection platforms (CreepJS and Bot.Sannysoft). The harness lives in server/, so run this from a checkout of the repo, or set OYA_SERVER_DIR:

# Run local evasion probe suite
oya stealth-test

# Run live benchmark against detection platforms
oya stealth-test --live

🤖 CI/CD & Headless Environments

In automated pipelines (GitHub Actions, GitLab CI, Docker), use flags or environment variables to bypass interactive prompts:

export OYA_API_KEY="oya_live_..."
export OYA_BASE_URL="https://oyabrowser.com"

# Non-interactive launch with JSON output
oya start --provider browserbase --persona auto --json

| Global Flag | Description | | :------------ | :---------------------------------------- | | --key <key> | Override API key for command | | --url <url> | Override control plane URL | | --id <id> | Target specific browser instance ID | | --json | Output pure JSON for programmatic parsing |

📄 License

MIT © Oya