Skip to main content

Usage and Command Reference

This page covers the complete supported MonoSurf command surface and the important compatibility boundaries around it. Verified against monosurf 0.11.3, OpenCLIs build 2026-07-19-222928.

Install and Inspect the Contract

monosurf with no arguments prints the current command and option guide. monosurf version prints only the installed version. The installed guide is the exact syntax authority when it differs from an older web page. OpenCLIs exposes the public discovery guide and command-aware wrapper steps:
The wrapper preserves the full native output and adds bounded guidance for browse, bridge, postcondition, start, stop, profile, and doctor, including the foreign-port and login/permission failure paths. Run the native binary directly when no wrapper guidance is needed.

Release Provenance

The current OpenCLIs release is monosurf 0.11.3, build 2026-07-19-222928. latest.json, every platform entry, the immutable monosurf-v0.11.3 tag, and the main branch all resolve to clean source commit 75af74b0132b5e9308f50c4e94b2c0407d814bc9 with source_dirty: false. All five platform archives are public and match immutable meta.json hashes. Each contains the same seven source-owned guide files, including initiate.json; their text matches the tagged source after normalizing Windows line endings. Those CLI archives do not bundle monolex-native-host. Main/public registry commit ade36c68f9d2e7cc1982b4412105e933317d6fe9 adds the explicit Monolex desktop prerequisite after the release tag; this is a documentation and registry correction, not a replacement artifact or changed release hash. The installed macOS payload reported monosurf 0.11.3, passed doctor, and completed a real extension/native-host bridge test using the shared host staged by Monolex desktop, with fixed extension id cclkmkgheebiiommelcnjindolniongm. The test imported an exact HttpOnly cookie with its security attributes, reopened the same managed profile, hydrated an empty target before navigation, verified the resulting session, and cleaned up the temporary state. Windows publication is intentionally separate from Windows trust policy. The 0.11.3 x86-64 archive was published and installed successfully, and the installed file had no Mark-of-the-Web stream; its Authenticode status was NotSigned. On its first installation, Windows 11 Smart App Control/WDAC Code Integrity events 3077 and 3033 rejected the new hash at the Enterprise signing level under policy {0283ac0f-fff1-49ae-ada1-8a933130cad6}. Rolling back made the previous trusted monosurf 0.10.5 payload runnable. A later 0.11.3 installation of the same verified payload executed successfully and returned a clean doctor report; no signing or hash change explains that transition. Treat execution of a new unsigned hash as host-policy and reputation dependent. The artifact was public throughout; an initial policy block is not evidence of an absent Windows release. A platform archive proves distribution and integrity. Direct execution proves runtime behavior only on the host where it ran; the ARM64 rows above are archive/format and CI witnesses, not local runtime claims. Kernel CLI 0.26.8 embeds the lib-monosurf 0.11.3 facade and lib-monosurf-core engine. Every command family on this page can also be entered after the kernel-cli websurf prefix. Both entry points share the command and state contract, profile TUI, profiles, plugins, grants, and browser state; neither needs to launch the other as a subprocess:
The standalone 0.11.3 artifact and Kernel CLI 0.26.8 expose the same facade, engine, command, and state contract. Their independently published executables are not byte-identical. The typed MCP websurf adapter intentionally exposes only plan, browsers, profiles, and site; use either terminal prefix for the complete compatibility surface documented here. When a page flow reaches browser chrome or a native dialog, leave the DOM surface and continue with Kernel CLI targetsact, then return to the page to verify. Kernel CLI 0.26.8 emits browser-aware guidance for shallow native targets, verified coordinate entry into a browser, and a browser URL hidden from accessibility. It also distinguishes a non-browser embedded webview from a CDP-attachable browser and binds route/order guidance with SOP v2. It still reserves websurf.native_dialog for a future positive handoff signal rather than emitting it from every web call. See the Kernel CLI routing contract.

Quick Start

Read a public page in a clean temporary session:
Create a persistent browser identity for logged-in work:

Supported Command Map

Command aliases

Profiles and Browser Engines

A profile is an isolated, persistent browser identity. Stopping its browser is normal: the login state lives in the profile and survives close and reboot. Removing the profile is the operation that deletes that state.

Profile commands

Selection order

Site and profile-backed commands resolve a profile in this order:
Browse deliberately has a safer final step: after explicit --profile, the environment, and the persistent default, it creates an ephemeral session. It does not silently adopt the only registered profile.

Browser discovery and engine pinning

MonoSurf can discover system Chrome and compatible Playwright, Puppeteer, or headless-shell Chromium installations. The first successful profile launch pins the browser kind and signing identity that own its encrypted cookies. If discovery later resolves a different kind, MonoSurf fails clearly instead of quietly presenting a logged-out profile. Use --allow-binary-change only when you accept the switch and expect to sign in again.

CDP port ownership guard

Version 0.11.3 never treats an open profile port as proof that MonoSurf launched the listener. A new profile skips every active unregistered port, launches on the selected free port, and proves that exact listener’s --user-data-dir before committing the profile record. Existing managed start, profile-backed connect, site-command, and batch paths apply the same ownership test. If a pid file points to a live, readable process whose command line belongs to something else, MonoSurf treats the number as recycled: it removes the stale record without killing the process. On Unix, port discovery filters for the LISTEN socket so a connected CDP client is not selected instead of Chrome. The exact chosen port is threaded through launch verification and failed-launch cleanup, avoiding a second allocation decision after Chrome has bound it.

Browse and Attach

MonoSurf has three ways to obtain a page session: Use --ephemeral to force a clean temporary session even when an environment or persistent default profile is configured. --profile and --ephemeral cannot be combined. With --cdp-url, a managed profile selection is ignored because the external endpoint owns the session. --use-profile <name> remains a browse-only alias for --profile <name>. The external Chromium-family process must already expose CDP, commonly by being launched with its own --remote-debugging-port=<port> flag. That is a browser launch option, not a MonoSurf option; MonoSurf receives the resulting endpoint through --cdp-url and never assumes ownership of the attached process.

Primary page output

Strict TLS is the default. A requested output that fails, times out, cannot be written, or navigates to an unreachable HTTP endpoint returns a non-zero exit instead of silently succeeding.

Browser QA and Dev Loop

The QA controls run inside the same CDP page session:
The bridge is an explicit cookie snapshot workflow, not profile reuse:
bridge install materializes the versioned unpacked extension, installs the existing Monolex shared native host under the monosurf-native-host routing name, and writes the native-host manifest. The extension’s manifest key pins ID cclkmkgheebiiommelcnjindolniongm; load the printed extension directory once from chrome://extensions with Developer mode enabled. The prerequisite is ~/.niia/bin/monolex-native-host, staged by the Monolex desktop app (monolex-native-host.exe on Windows). The standalone monosurf 0.11.3 archives do not bundle it. When it is absent, bridge install exits non-zero after it may already have materialized the unpacked extension assets; do not load that partial result as a completed bridge installation. Install or launch Monolex desktop to stage the matching shared host, then rerun the command. For each import, start bridge first, open the logged-in target tab in Chrome, then click the extension’s Sync action. The receiver filters expired entries and writes the active tab’s matching cookies to the OpenCLIs Vault-backed snapshot. Before a later JSON site command navigates, the live jar is read first. Only an empty jar is hydrated; a non-empty live session always wins. Hydration validates every scope, supplies an explicit HTTP(S) origin, preserves domain, path, HttpOnly, Secure, SameSite, and expiry, and fails the whole command on any invalid scope or CDP error. It does not copy localStorage, IndexedDB, service workers, passwords, the daily Chrome profile, the Chrome process, or cookies unrelated to the active tab. The Monolex Agent Browser path is intentionally different: Sign In with Chrome → Open in Agent reuses one owned managed profile so cookies, localStorage, IndexedDB, service workers, and passkey state stay together without serialization. It never adopts or relaunches daily Chrome. OpenCLIs Vault owns stable protected snapshot storage; MonoPass owns passkey/WebAuthn ceremonies.

Bound Navigation and Toast Proof

Use postcondition when one click and its evidence must be inseparable:
The command scopes an exact normalized-text link or button to one container, reveals it, performs a real CDP click, and reports before/after canonical URL, history length, scroll, viewport intersection, destination target, and fixed- header clearance. Duplicate controls, missing targets, URL drift, covered/off-screen targets, and bounded timeouts return non-zero. For actions whose success is a visible message and intentionally unchanged URL:
The supported timeout range is 250–30000 ms.

Harvest Growing Pages

--collect repeatedly extracts matching elements, scrolls, deduplicates, and streams each new item as JSONL. It makes a feed that stopped growing visible instead of returning an unexplained partial result.
Items flush as they arrive, so an interrupted long run keeps the JSONL already written. The end report includes item and round counts, first and last keys, and a stall_reason such as max_items, max_rounds, no_growth, or an evaluation error. Zero collected items and failed collection evaluation return non-zero.

Capture Page Network Traffic

--net-log <file> records every CDP network response as JSONL from before navigation through the end of the session. It can reveal media manifests, original CDN assets, and XHR endpoints that never appear in the DOM. Combine network logging with collection in one pass. This avoids scrolling a feed once for DOM items and again for the network evidence behind them.

Logged-In Site Commands

Site commands come from installed JSON plugins. Read actions require an active read grant; posts, replies, deletes, and other writes require a write grant. The installed plugin remains the authority because local and registry plugins can evolve independently of the binary. Current bundled domains expose these command names:
Run monosurf sites to inspect installed domains. Use monosurf sites search <query> to see their declared command names and tags.

Grants, Login, and Batch Posting

Time-limited grants

Read and write are separate scopes. auth status is read-only and also reports which secure storage backend currently owns each known session key.

Login

Login opens the selected profile for manual authentication and preserves the live browser session. The protected session snapshot can bootstrap an empty cookie jar, while an already-live browser session wins when the site rotates tokens.

Batch posting

A site plugin starts the background job. batch status reports progress and the next post; batch stop finishes the current post and stops gracefully. Separate posts in the input file with --- on its own line. The first post is sent immediately, then the interval and jitter apply.

Site Plugin Management

See Site Plugins before authoring or publishing a workflow that will run inside a logged-in session.

Safety, Health, and Self-Tests

Doctor

monosurf doctor is read-only by default. It compares registered profiles, profile directories, process records, the default pointer, and temporary session leftovers.

Offline self-tests

Each self-test is local and returns non-zero when its hard contract fails.

Embedded documentation

These topics travel with the installed binary and explain profile persistence, engine identity, doctor safety classes, grants, and secret-storage boundaries.

Legacy Compatibility Entry Point

The old cookie-source selector remains only as a compatibility message: This boundary prevents a legacy platform selector from being mistaken for silent Chrome-profile extraction. bridge is now the supported, user-triggered cookie-only path; it is not an alias for profile cloning.

When to Hand Off to Kernel CLI

MonoSurf can operate only inside the CDP-visible page. Hand the workflow to Kernel CLI when it reaches:
  • a native file, print, or save dialog;
  • Face ID, Keychain, or another operating-system permission prompt;
  • the browser address bar, tabs, menus, extensions, or other browser chrome;
  • a non-Chromium desktop application.
See Kernel CLI Complete Command Reference for the native observation, accessibility, OCR, input, app, and window surfaces.

MonoSurf Overview

Understand the page boundary, connection modes, and companion-tool map.

Site Plugins

Learn how installed domains expose reusable read and write commands.

Auth Gate

Review grants and protected session access in more detail.

Kernel CLI

Continue automation across the native desktop outside the web page.