# Unicli Browser > Control broker-owned hidden, existing-Chrome, or remote browser targets with explicit Agent identity, visibility, profile partitions, and lifecycle. - Skill: `olo-dot-io/unicli-browser` (Agent Skill) - Install (CLI): `npx skillmds@latest add olo-dot-io/unicli-browser` - Raw SKILL.md: https://api.skillmd.com/api/skills/olo-dot-io/unicli-browser/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: olo-dot-io (https://skillmd.com/u/olo-dot-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/olo-dot-io/unicli-browser --- ## 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 ```bash 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 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. ```bash 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: ```bash 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 ```bash 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 ```bash unicli browser profiles --json unicli browser cookies --profile-id # Explicit persistence unicli auth import --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 ```bash 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: ```bash 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 |