kernel 0.26.8, OpenCLIs build
2026-07-19-224153. Run kernel-cli --version and kernel-cli --help for the
installed contract on your machine.
Quick Start
doctor is the first command to run on a new machine. It reports live
permissions, desktop-session state, helper availability, and the capability
families that are ready now.
Run kernel-cli with no arguments for the full live agent reference. Use
kernel-cli --help for the concise command inventory, kernel-cli <command> --help for exact arguments and options, and kernel-cli docs for the
conceptual and platform guides embedded in the installed binary. These surfaces
serve different questions and travel with the release.
OpenCLIs also publishes the discovery and wrapper guide:
[NEXT] object; that native object owns
the evidence-backed route for the result that just ran.
The Mental Model
Kernel CLI starts with the least ambiguous source and escalates only when the task needs it:Five Capability Surfaces
Observe
Read snapshots, windows, displays, accessibility trees, actionable targets,
rendered text, app data, logs, and reactive wait/watch conditions.
Control
Act on target handles, press or set accessible elements, type, send keys,
control apps and windows, use menus, and fall back to pointer input.
System
Inspect processes, hardware, CPU, power, devices, ports, routes, proxy,
security posture, services, schedules, backups, logs, and session state.
Web
Use
kernel-cli websurf for DOM, JavaScript, CDP, persistent browser
profiles, site plugins, feed collection, and browser QA.MCP
Expose the raw command surface as typed tools, with structured health data
and an optional
computer_use compatibility facade.Observe, Resolve, Act, Verify
The preferred interaction loop is:- Observe structured state with
snapshot,windows,ax-tree, ortargets. - Resolve a semantic target and keep its
snapshot_idandtarget_id. - Preview the write with
act --dry-run. - Act only after the target and backend are clear.
- Read back the resulting state before trying a fallback.
Result-Guided Routing
Version 0.24.8 adds a shared routing catalog behind the literal[NEXT]
marker. Discovery surfaces explain the golden flow before work begins, while
selected command results recommend the strongest evidence-backed next step:
Embedded help and docs can also contain their own static discovery
[NEXT]
section; that is separate from the one dynamic result recommendation.
Guidance is based only on facts established by the current invocation. It does
not probe or mutate extra state, replace the primary result, grant a missing
capability, or change the exit code. Unknown or ambiguous internal states stay
silent instead of suggesting a guessed route.
The main routed results are doctor, targets, elements, ax-tree, act,
read-text, url, coordinate click, and script. Mapped permission,
stale-target, off-screen, ambiguity, and app/focus errors also receive specific
recovery guidance. The current 0.26.8 runtime routes classified failures centrally, so a
mapped error receives the same catalog route even when its command branch has
no local emitter; an invocation still emits at most once. MCP adds guidance for
an unknown docs topic. The
websurf.native_dialog id is catalogued for a future positive native-handoff
signal but is not appended to every web call. Run kernel-cli docs agent-flow
for the complete DOM → AX → OCR → coordinate decision ladder.
The fused-targets precedence introduced in 0.24.9 remains the 0.26.8
behavior. If a result contains any semantic AX handle, the route is
targets.actionable even when OCR fallbacks in that same result carry
structured-value or low-confidence warnings. OCR trust warnings own the route
only when no semantic handle exists.
CLI and native MCP call the same routing function, so the two surfaces cannot
silently disagree about this priority.
Version 0.24.10 adds three browser-aware routes only when the current invocation
has browser evidence. Empty targets, elements, or ax-tree results scoped
to a Chromium-family app emit targets.browser_shallow; a coordinate click
with an enforced browser identity emits coordinate.into_browser; and a
confirmed browser whose URL is hidden from accessibility emits
url.native_unreadable. These routes send page work to websurf, keep browser
chrome and native dialogs on Kernel CLI, and stay generic or silent when the
browser fact is absent.
Version 0.24.11 advances the guidance object to schema v2 with a sop binding
level:
The same release adds
ax_tree.webview_content. It emits only when an explicit
non-browser --app scope returns a real web-content subtree and the caller did
not already provide --web-depth. That evidence means the embedded webview is
reachable through deeper AX by app name; it does not make the app a
CDP-attachable browser. Version 0.24.11 also gives 31 related commands static
sibling-aware --help epilogues, while dynamic result routing remains owned by
the guidance catalog.
Raw Capability and Harnessed Access
Kernel CLI and NIIA own different layers:
Kernel CLI maintains a local mutating-command audit log, but that log is not an
authorization boundary. NIIA is the layer that decides whether a write may run.
Embedded Web Surface
kernel-cli websurf links the reusable lib-monosurf 0.11.3 facade and its
lib-monosurf-core engine directly into Kernel CLI. Standalone
MonoSurf and the embedded namespace therefore use one
canonical help surface, embedded documentation tree, profile TUI, planner, and
runtime:
Application Support/Monolex/monosurf/. Kernel CLI executes
the shared facade in-process; it does not launch a standalone monosurf
subprocess. Installing standalone MonoSurf is therefore optional when you
already use kernel-cli websurf; it remains useful as an independently
versioned, web-focused entry point. Use the MonoSurf command
reference for the complete compatibility surface and Kernel
CLI for browser chrome, native dialogs, and other OS UI.
Kernel CLI 0.26.8 embeds the same MonoSurf 0.11.3 facade published by the
standalone release. Managed profile allocation skips active unregistered CDP
ports, then proves ownership against the exact chosen port before committing
the profile record. A foreign owner is refused immediately; temporarily
unavailable ownership metadata is retried for a bounded interval and still
fails closed if it cannot be proved.
The explicit bridge path is a cookie-only bootstrap, not Chrome profile reuse:
run kernel-cli websurf bridge install, start bridge [domain] (or add
--keep), and click Sync in the fixed-ID extension. This requires the
~/.niia/bin/monolex-native-host staged by Monolex desktop (.exe on Windows);
the Kernel CLI 0.26.8 archive does not bundle that shared host, and a missing
host makes bridge install fail non-zero. Before a site command
navigates, an empty live jar may be hydrated with an explicit HTTP(S) origin
while preserving domain, path, HttpOnly, Secure, SameSite, and expiry. A
non-empty live jar wins, and invalid cookie scope or any CDP write error aborts
the command. This route never copies localStorage, IndexedDB, service workers,
passwords, the daily Chrome profile, or the daily Chrome process. Use the
Monolex Agent Browser’s same-profile login path when that complete browser
state must be retained.
Version 0.26.8 has 109 root commands and exposes the same complete browser
surface as standalone MonoSurf 0.11.3. Use postcondition navigation to bind
one click to URL/history/viewport/target/header evidence, or postcondition toast for success that deliberately leaves the URL unchanged.
Profiles, Collections, and Focus Politeness
Application profiles turn repeatable native UI operations into named gestures. Version 0.25.0 adds a geometry context: coordinate-sensitive gestures compare the current window frame with the frame they were authored against. Run with--conform to move or resize first, or use profile rebaseline <app> to adopt
the current frame. profile describe also exposes parameter value hints, and
read-text plus click-text can scope OCR to --app or an exact --window
so another window’s pixels are not mislabeled as the target app.
Version 0.26.0 adds the collection distribution layer over those profiles:
script, open, or
shortcut steps, and re-anchors foreign geometry to this machine. Receipts
prevent an update from silently replacing local edits; --force is explicit.
--from <path-or-url> uses the same validation path for a sideload, while
collection publish is the owner-side publication command.
collection list and collection show disclose geometry sensitivity before
installation or execution. [frame-bound N] counts gestures whose absolute
coordinates require the authored window frame (use --conform or
profile rebaseline); [size-scaled N] counts relative drags whose feel
changes with window size. A pack with neither badge is size-free.
Exact window and menu recovery controls remove two common sources of ambiguous
desktop writes:
window --id conflicts with --title, so one invocation cannot silently name
two windows. Normal macOS menu invocation cleans up any AX-opened residue;
menu close [--app X] is the explicit recovery path, and a cleanup failure is
reported instead of hidden.
Version 0.26.1 makes profile-authored workflow guidance observable instead of
leaving it as inert JSON. A profile-level note (with legacy _note accepted
as an alias) explains the pack; each gesture may add its own note and a
next array. profile describe prints those contracts, its JSON form keeps
the complete profile note, and a successful gesture returns its
parameter-resolved follow-ups under next or a human [NEXT] declared by the profile: block. These author hints cannot override the engine-owned intent or
focus tags.
Gestures can declare whether they require foreground focus, can run entirely
in the background, or should yield while a human is actively using the
machine. Machine defaults live under the focus object in
~/.kernel-cli/config.json; callers can add gesture --yield, bound the wait
with --yield-timeout, and return the desktop with --restore-focus. In
0.26.1, a busy macOS handoff uses a visible dialog: OK consents
immediately, Cancel/Esc refuses with focus_busy, and simply pausing input
lets the idle threshold complete the handoff. Cancel is the default button;
non-macOS systems and a failed dialog launch keep the notification-plus-idle
fallback. For a multi-process gesture chain, read frontmost once before the
first gesture and pass that app to the last gesture with --restore-to <app>.
This explicit target implies restore and activates the named app even though
intermediate gestures have changed which app appears previous. The
atomic paste_via_menu profile step saves, replaces, uses, and restores the
clipboard as one operation, reducing both clipboard pollution and the race
window around menu-driven text entry.
Cross-Platform Contract
Kernel CLI presents one behavioral order across macOS, Linux, and Windows:- macOS has the broadest native surface, including Accessibility, Vision OCR, Screen Recording, system telemetry, app/window control, and optional device-level input.
- Linux uses AT-SPI and the active desktop session, plus helper tools for input, clipboard, capture, and OCR where required. Pure Wayland sessions may restrict global input or capture.
- Windows uses UI Automation and Win32 in the interactive desktop session, with OCR dependent on installed language support.
doctor is the
live truth for the current machine and session.
CLI and MCP Are the Same Capability Family
Run the MCP server with a subcommand:computer_use, health_report, connections, trackpad, and type_text.
Version 0.26.2 first mapped collection; 0.26.3 closes its safety contract.
Because one static MCP definition contains both read actions and
install/update/publish, it is classified by its most mutating action:
readOnlyHint: false, destructiveHint: true, idempotentHint: false, and
openWorldHint: true, with tooling.control, network.read, and
network.write capabilities. Only install, update, and publish enter the
mutating audit and trajectory stream; list, search, show, and the default list
action remain read-only at execution time. The server also provides structured
results and result guidance.
The MCP websurf tool is a typed adapter with plan, browsers, profiles,
and site operations. plan declares effects without executing them; the two
discovery operations read local state; and site executes a typed plugin
operation. The complete browser compatibility surface remains available at
kernel-cli websurf.
The facade provides a familiar usage shape; it does not imply that Kernel CLI
shares the same driver architecture as other computer-use systems. The raw CLI
and raw MCP tools remain available.
Where Next
Workflows
Install, diagnose, observe, dry-run, act, verify, and use the NIIA harness.
Reference
Command families, platform boundaries, permissions, MCP setup, and
operations.
MonoSurf
Learn the complete command surface shared by standalone MonoSurf and the
embedded
kernel-cli websurf namespace.The Harness
Why raw capability and human authorization are separate layers.
Install OpenCLIs
Install the OpenCLIs package manager before installing Kernel CLI.