browser-cli

# browser-cli Use `browser-cli` as the primary interface for Lexmount browser automation. Prefer CLI commands and JSON output over importing Python internals or writing ad hoc Playwright scripts. ## Use When Use this Skill when a task needs a Lexmount remote browser rather than a local tab: browsing, website testing, login reuse, inspection, forms, screenshots, content extraction, browser state setup, diagnostics, or repeatable case files. Use the Fast Path below: do not run reference, doctor, or action-guide discovery before every CLI command. Run the target command directly when credentials, session, and action are already clear. Do not use this Skill for local desktop app control, already-open local browser tabs, static docs lookup, or tasks that do not need Lexmount credentials; for static page retrieval, agent-readable article extraction, or DOM dumping that does not require an interactive remote browser session, consider the optional companion `webfetch-cli` first, not as a browser-cli dependency, and check `webfetch-cli --version`, `webfetch-cli capabilities --json`, `webfetch-cli extract`, or `webfetch-cli dump-dom` when it would avoid opening a browser. ## Supported Operations - Setup and auth: install/version checks, credential state, scoped-token metadata, Connect from Codex requirements, doctor readiness, and smoke-session cleanup. - Sessions: create, list, get, keepalive, close, and recover stale sessions; Contexts: create, list, get, status, pick, delete, reuse by metadata, and explain `available`/`locked`/`unavailable` decisions. - Navigation and readiness: open URLs, reload, history navigation, and waits for URL, title, load state, network idle, selectors, roles, text, attributes, values, frames, dialogs, storage, cookies, console, and fetch/XHR. - Inspection and extraction: observe/extract/page-info plus interactive, text, links, tables, lists, forms, dialogs, frames, accessibility, network, console, performance, and screenshots. - Interaction: act, click-label, click-text, click-role, click-index, fill, select, check/uncheck, hover, press, focus/blur, scroll, drag, file uploads, dialogs/frames, and storage/cookie state changes. - Repeatable automation: validate, scaffold, and run JSON/YAML cases with artifacts, events, expectations, and cleanup for reproducible tasks. ## Fast Path Avoid repeated setup discovery. For ordinary browser work, run the next necessary command directly, for example `browser-cli auth status`, `browser-cli session create`, `browser-cli action open-url --session-id <session_id> --url <url>`, `browser-cli action snapshot --session-id <session_id>`, then `browser-cli session close --session-id <session_id>`. Run heavier checks only when they change the next action: first use in a new environment (`browser-cli --version`, `browser-cli auth status`); missing/unclear credentials (`browser-cli auth login --open`, then `browser-cli doctor --json`); no recent successful auth/status signal before creating a browser session (`browser-cli doctor --json`); unclear command/API failure (inspect JSON error, then doctor if still unclear); unsure command shape (`browser-cli commands --names-only`, `browser-cli commands --workflow <id>`, or `browser-cli reference list`); unsure action arguments (`browser-cli action guide --task <task>`); stale skill (`browser-cli skill status`, then `browser-cli skill install --force` only if needed). ## Setup If the CLI is not installed, install it with: ```bash uv tool install --force https://github.com/lexmount/browser-cli/archive/refs/heads/main.tar.gz ``` The source archive is the preferred official path because it does not require system git. If and only if that exact command fails because GitHub archive/codeload access is blocked, first confirm `git --version` succeeds, then use the official fallback `uv tool install --force git+https://github.com/lexmount/browser-cli.git`. Both commands download and execute package build code. A coding agent may require normal command approval; show the exact command and request approval instead of bypassing the gate with clone/local-path tricks. Do not web-search for alternative packages, guess another repository/download host, or substitute another console origin. If both official commands fail, stop and report both errors. Authorize with the local loopback PKCE flow: run `browser-cli auth login --open`, then `browser-cli auth status` and `browser-cli doctor --json`. Do not ask the user to paste secrets into chat. Direct the user to the exact console origin supplied by the current setup. Treat that origin as authoritative and do not substitute another console host. If no console origin is supplied, China region authorization defaults to `https://browser.lexmount.cn`. `auth login --open` starts a `127.0.0.1` callback, opens Connect from Codex, validates `state`, and exchanges a one-time code plus PKCE verifier for local credentials. API keys do not appear in the local callback URL. China defaults to `https://api.lexmount.cn`; set `LEXMOUNT_BASE_URL` only for non-default APIs. Use local auth helpers instead of handling secrets in chat: ```bash browser-cli auth status browser-cli auth status --credentials-file ~/.config/lexmount/browser-cli/credentials.json browser-cli auth scopes browser-cli auth scopes --scope browser:actions --include-site-contract browser-cli auth token-info --required-scope browser:actions browser-cli auth refresh --credentials-file ~/.config/lexmount/browser-cli/credentials.json browser-cli auth logout --credentials-file ~/.config/lexmount/browser-cli/credentials.json browser-cli auth clear-credentials --credentials-file ~/.config/lexmount/browser-cli/credentials.json browser-cli auth connect-requirements browser-cli auth login browser-cli auth login --open browser-cli auth login --device-code browser-cli auth export-env ``` When setup or auth is unclear, inspect the installed workflow contract first: ```bash browser-cli commands --workflow setup_and_verify browser-cli commands --workflow connect_from_codex_site_requirements browser-cli commands --workflow connect_from_codex_auth browser-cli commands --workflow device_code_auth browser-cli commands --workflow scoped_token_lifecycle ``` When the task is to inspect or explain what browser.lexmount.cn must implement, run `browser-cli reference get --id connect_from_codex`, `browser-cli auth scopes --include-site-contract`, `browser-cli auth connect-requirements --checklist`, or `browser-cli commands --workflow connect_from_codex_site_requirements` first. Read `browser_site_contract.scope_ui_fields`, `browser_site_contract.browser_site_acceptance_tests`, `known_scopes`, `default_scopes`, `connect_from_codex.site_capability_status.missing`, `required_device_code_endpoints`, `required_api_contract`, `required_token_lifecycle`, `required_runtime_auth`, `setup_blocks`, `implementation_checklist.phases`, `implementation_checklist.blocked_until`, and `verification.doctor_command`. Prefer `browser-cli auth login --open` when credentials are missing. Inspect top-level `selected_flow`, `authenticated`, `credentials_saved`, `reason`, `open_result`, `loopback_callback`, `exchange`, and safe `credentials` metadata. If it succeeds, run `browser-cli auth status` and `browser-cli doctor --json`. If it cannot complete, use the returned `handoff` as the manual fallback contract: follow `copyable_commands`, local shell env guidance, and `verification.doctor_command`. Follow `secret_policy`: never paste `LEXMOUNT_API_KEY`, revealed export output, authorization codes, code verifiers, or full direct URLs into chat. If the user asks for device-code login, run `browser-cli auth login --device-code` and parse `available`, `reason`, `device_code`, `polling`, `credentials`, and `fallback_handoff`; while `available` is false, guide the user through the manual env fallback. When an endpoint is explicitly configured, use `--wait` only after approval instructions are visible; never report access, refresh, or raw device-code values. Prefer `browser-cli commands --workflow device_code_auth` when the task is to inspect or explain the device-code authorization path. `auth export-env` prints placeholders by default. With `--from-current`, it still masks `LEXMOUNT_API_KEY` unless `--reveal-secrets` is explicitly used in a trusted local terminal. Check top-level `usable` and `unusable_exports`, plus `safe_to_paste_in_chat`, `local_shell_only`, `contains_secret_values`, `contains_secret_placeholders`, `safety`, `setup_block`, and `verification.doctor_command` before treating returned `commands` as runnable; only run local-shell setup blocks in the user's local terminal, never in chat. `auth status` reports `auth_source`, `runtime_auth_usable`, `runtime_auth`, safe `api_key_credentials`, and safe `device_token` metadata. Read `runtime_auth.usable`, `runtime_auth.source`, and `runtime_auth.bearer_runtime.required_support` before choosing a credential source. When env credentials are incomplete, read `missing_env` and the `fix` object instead of inventing setup steps. Use `auth scopes` to inspect known Connect from Codex scopes, `default_scopes`, `permission_count`, `risk`, `destructive`, `unknown_scopes`, and the optional `browser_site_contract` before explaining requested permissions. Use `auth token-info --required-scope <scope>` to check scoped-token coverage. Use `auth refresh --credentials-file <path>` to inspect `refresh_needed`, `has_refresh_token`, `refresh_available`, `refreshed`, `reason`, `refresh_endpoint`, and `remote_refresh`; add `--token-base-url <url>` or set `LEXMOUNT_BROWSER_TOKEN_BASE_URL` when browser.lexmount.cn exposes `POST /api/auth/token/refresh`. `remote_refresh` reports safe metadata such as `response_payload_source` and `response_summary`; token data may be top-level or under `token`, `device_token`, `credential`, or `credentials`. Use `auth clear-credentials --credentials-file <path>` to delete local browser-cli credentials, including API-key credentials or device-token metadata, without changing the parent shell; inspect `unset_env_commands` when env variables are still present. Use `auth logout --credentials-file <path>` for the device-token lifecycle flow; `--revoke` calls `POST /api/auth/token/revoke` only when a token lifecycle base URL is configured. Treat explicit `remote_revoke.revoked=false` as not confirmed. These commands never report access or refresh token values. Until bearer-token runtime support lands, require env API-key credentials for browser actions when `runtime_auth.usable` is false. For scoped token checks, refresh, or local logout, prefer the lifecycle workflow: ```bash browser-cli commands --workflow scoped_token_lifecycle ``` Follow its `read` fields for `device_token.valid`, `scope_check.missing_scopes`, `refresh_available`, `refreshed`, `revoke_available`, and `warnings`. For the current usable baseline, readiness fields, and browser.lexmount.cn boundary, read `browser-cli reference get --id usable_status`. After credentials are configured, run: ```bash browser-cli doctor --json browser-cli doctor --smoke-session ``` Run `browser-cli doctor --json` before creating a browser session only when there is no recent successful auth/status signal, after credential changes, or when a session/context/action command fails for an unclear reason. Use `browser-cli doctor --smoke-session` only when you need proof that credentials can create and close a temporary browser session. `--json` is accepted as a no-op compatibility flag at the top level and after subcommands; browser-cli output is always JSON. Parse the JSON before deciding what to do: - `ok: true` and `failed: 0`: continue with browser work. - `ready_for_browser_actions: true`: browser sessions/actions can be attempted. - `browser_smoke_session` with `status: "pass"`: a temporary browser session was created and closed. - `browser_smoke_session` with `status: "fail"`: follow its `fix` commands, especially a manual `session close` command when `created` is true and `closed` is false. - `command_catalog` with `status: "warn"`: inspect `missing_required_commands`, `missing_required_agent_entrypoints`, `invalid_workflow_command_references`, and `invalid_agent_entrypoint_command_references`; if `action_guides` warns, inspect `missing_required_action_guides`, `invalid_action_guides`, and `invalid_guide_command_references`; follow its `fix` guidance before relying on the full Skill workflow. - `case_schema` with `status: "warn"`: inspect `missing_required_case_actions`, `missing_case_scaffold_templates`, `checked_case_scaffold_templates`, `invalid_case_scaffold_templates`, `missing_action_schemas`, `invalid_action_schemas`; reinstall if needed. - `auth_login_contract` or `device_code_contract` with `status: "warn"`: inspect `missing_handoff_fields`, `missing_setup_blocks`, `missing_required_device_code_endpoints`, `missing_required_browser_site_support`, `invalid_fields`, and `secret_policy`; reinstall if needed. - `agent_references` with `status: "warn"`: run `browser-cli reference get --id quickstart`, `browser-cli reference get --id action_playbook`, or follow its `fix` commands before relying on detailed setup or action guidance. - `agent_examples` with `status: "warn"`: run `browser-cli example list`, inspect `invalid_examples` and `checked_examples`, and reinstall browser-cli if packaged playbooks or case files are unreadable or invalid. - `repair_plan`: prefer its aggregated `commands`, `env`, `guidance`, and `fixes` when explaining setup repair steps. - `warnings > 0` or a check with `status: "warn"`: continue only after reporting warning check names and any `fix` guidance; warnings usually mean local installation/PATH hygiene rather than unusable credentials. - `ok: false`: stop before creating sessions, inspect `checks` with `status: "fail"`, and follow each check's `fix` object when present. - `api_connectivity` with `status: "skipped"`: do not treat live API access as verified. - `env.LEXMOUNT_BASE_URL` with `status: "fail"` and `value_internal: true`: unset it, rerun `browser-cli auth login --open`, and verify a public API base URL before browser work. Use `browser-cli doctor --skip-api` only for offline setup checks or when the user explicitly asks to avoid a live API call. Do not treat a skipped API check as proof that browser sessions will work. Run `browser-cli commands --workflows-only` for a compact agent workflow map, `browser-cli commands --workflow <id>` for one task path, and `browser-cli commands --names-only`, `browser-cli commands --group action`, or `browser-cli action guide --task <task>` when the installed CLI version is uncertain or before writing custom JavaScript. Use the catalog's `browser_target.exactly_one_of`, `required_options`, `required_one_of`, `json_output`, `secret_policy`, `agent_references`, `agent_examples`, `agent_entrypoints`, and `agent_workflows` fields instead of parsing `--help` text. Follow `agent_references` when detailed action guidance is needed; use `browser-cli reference get --id connect_from_codex` for browser.lexmount.cn requirements, `browser-cli reference get --id usable_status` for the current usable baseline, and `agent_references.action_playbook.content_command` or `browser-cli reference get --id action_playbook` for action guidance from an installed CLI. Use `browser-cli example list` and `browser-cli example get --id setup_verification_playbook`, `browser-cli example get --id auth_lifecycle_playbook`, `browser-cli example get --id persistent_context_playbook`, `browser-cli example get --id page_inspection_case`, `browser-cli example get --id agent_primitives_case`, `browser-cli example get --id form_fill_case`, `browser-cli example get --id content_extraction_case`, `browser-cli example get --id browser_state_case`, `browser-cli example get --id navigation_flow_case`, `browser-cli example get --id file_upload_case`, `browser-cli example get --id checkout_flow_case`, `browser-cli example get --id interactive_targeting_case`, or `browser-cli example get --id page_diagnostics_case` when a common task or case file template would help. Use `browser-cli case scaffold --template page-inspection`, `browser-cli case scaffold --template agent-primitives`, `browser-cli case scaffold --template content-extraction`, `browser-cli case scaffold --template browser-state`, `browser-cli case scaffold --template navigation-flow`, `browser-cli case scaffold --template file-upload`, `browser-cli case scaffold --template checkout-flow`, `browser-cli case scaffold --template interactive-targeting`, or `browser-cli case scaffold --template page-diagnostics` to generate a valid starter case before hand-writing YAML, then follow each workflow step's `read` array first; it names the auth availability, export usability, and context reuse fields that drive the next decision. ## Workflow