unicli-browser

name	unicli-browser
description	Control broker-owned hidden, existing-Chrome, or remote browser targets with explicit Agent identity, visibility, profile partitions, and lifecycle.
version	2.0.0
triggers	["browser automation","control chrome","unicli browser","background browser"]
allowed-tools	["Bash"]
protocol	2

When to Use

Use unicli browser for browser lifecycle, page interaction, session sharing, target handoff, and diagnostics. unicli operate is a compatibility alias for the page-action subset.

Provider Decision

Requirement	Provider and visibility
No window; default automation	managed + hidden (default)
Existing signed-in Chrome tab, no activation	chrome + background
Explicit user-visible Chrome interaction	chrome + foreground
Explicit cloud/browser service	remote + hidden

No provider falls back to another. Managed and remote providers cannot become foreground. Existing Chrome cannot promise hidden operation.

Quick Start

unicli browser doctor --json             # Probe only; starts nothing
unicli browser broker start              # Start windowless control plane only
unicli browser start                     # Lazily start default managed hidden target
unicli browser open https://example.com
unicli browser state
unicli browser click <ref>
unicli browser screenshot ./page.png
unicli browser sessions --json

Agent Sessions and Reuse

A stable Agent session owns targets across turns. Different Agent sessions use different targets, while a shared profile partition can reuse login/storage.

unicli browser --session thread-42 --turn turn-1 open https://example.com
unicli browser --session thread-42 --turn turn-2 state
unicli browser --session thread-42 --turn turn-3 click 7
unicli browser sessions --json
unicli browser session-end thread-42

Use --profile-partition team-login to share storage deliberately. Use --isolated for a disposable browser context inside that partition. --workspace is a compatibility spelling for the same partition concept.

Existing Chrome Without Foreground Activation

Install the native host and extension once, keep an existing normal Chrome window open, list tabs, then claim a specific tab:

unicli browser native-host install
unicli browser --provider chrome --visibility background tabs
unicli browser --session thread-42 --provider chrome --visibility background bind 123
unicli browser --session thread-42 --turn turn-2 --provider chrome --visibility background state

Background allocation must preserve focused window and active-tab state. If Chrome cannot satisfy that postcondition, the command fails instead of opening or focusing a window. Use --focus only for an explicit foreground request.

Broker Lifecycle

unicli browser broker status
unicli browser broker start
unicli browser broker restart
unicli browser broker stop

The broker is one authenticated, owner-only local control plane. Starting it does not start Chrome. Browser processes are provider-owned and lazy. Session TTL and target leases are visible through browser status and browser sessions.

Authentication and Profiles

unicli browser profiles --json
unicli browser cookies <domain> --profile-id <id>  # Explicit persistence
unicli auth import <site> --domain <domain>        # Explicit persistence

Managed runtimes use Uni-CLI-owned profiles under ~/.unicli/; they never run CDP against Chrome's default user-data-dir. A selected local profile seeds the automation profile. --ephemeral explicitly selects an empty profile.

Chrome 136+ ignores remote-debugging switches on its default data directory. RemoteDebuggingAllowed=false blocks even Uni-CLI automation profiles until an administrator removes the policy or sets it true. The policy does not make the default-profile CDP path supported.

Remote Browser

export UNICLI_CDP_ENDPOINT='wss://browser.example/devtools/browser/...'
export UNICLI_CDP_HEADERS='{"Authorization":"Bearer ..."}'
unicli browser remote
unicli browser --provider remote --visibility hidden start

Status redacts credentials, paths, query tokens, and headers. Malformed remote configuration is a hard error and never falls back locally.

Page Workflow

1. open the URL.
2. state to obtain current refs.
3. Use click, type, select, or keys with those refs.
4. Run state again after navigation or DOM replacement.
5. Prefer captured JSON APIs when network reveals a stable endpoint.

Useful commands:

unicli browser find --css 'button'
unicli browser query 7 --kind attributes
unicli browser frames
unicli browser console
unicli browser network
unicli browser extract --chunk-size 8000
unicli browser evidence --render-aware

Diagnostics

unicli browser doctor --json is the routing truth:

• default_path: managed/hidden availability and profile source.
• broker: stopped, running, or exact endpoint error.
• providers: managed runtimes, Chrome native-host state, redacted remote state.
• sessions: live Agent turns, target leases, and tombstones.
• checks[*].next_step: exact repairs.

unicli browser doctor --repair starts only the broker. It never starts a browser provider and never creates an about:blank placeholder target.

Problem	Exact next action
Broker unavailable	unicli browser broker restart
Managed browser unavailable	Install Chrome or use explicit --ephemeral
Chrome provider unavailable	Install native host/extension and keep a normal Chrome window open
Remote config invalid	Correct or unset UNICLI_CDP_ENDPOINT / UNICLI_CDP_HEADERS, restart broker
Exit 77	Restore auth with explicit profile/cookie flow