browser-cli

name

browser-cli

description

Operate Lexmount remote browsers with browser-cli. Use when a coding agent needs to create, list, inspect, keep alive, or close browser sessions; manage persistent contexts, pick reusable contexts, or detect locked contexts; guide authentication with auth status/scopes/token-info/refresh/logout/clear-credentials/connect-requirements/export-env/login; verify installation, environment, and API connectivity with doctor; discover installed commands/workflows; read packaged references with reference list/get; inspect packaged playbooks and case examples with example list/get; validate/run JSON/YAML browser case files; open pages, read page info, wait for selectors/states/roles/URLs/load/network/text/forms/dialogs/frames/console/fetch-XHR, act/click/type/fill/select/check/hover/press/scroll, inspect interactive/accessibility/page diagnostics, manage storage/cookies, navigate, screenshot, eval, snapshot, or verify credentials without custom Playwright.

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:

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:

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:

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:

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:

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