Usage and Command Reference
This page covers the complete supported MonoSurf command surface and the important compatibility boundaries around it. Verified againstmonosurf 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:
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, build2026-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:
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 targets → act, 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: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:--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
--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:Chrome Cookie Bridge
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
Usepostcondition when one click and its evidence must be inseparable:
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: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
auth status is read-only and also reports
which secure storage backend currently owns each known session key.
Login
Batch posting
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
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.
Related Guides
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.