> ## Documentation Index > Fetch the complete documentation index at: https://docs.monolex.ai/llms.txt > Use this file to discover all available pages before exploring further. # Kernel CLI > The CLI-first machine capability surface for AI: structured OS observation and control, machine telemetry, embedded web automation, and typed MCP tools across macOS, Linux, and Windows. Kernel CLI is the operating-system surface where AI meets the local machine. It combines desktop observation and control with machine telemetry in one CLI-first binary, so an agent can inspect what the OS already knows before it falls back to screenshots and coordinates. *Verified against `kernel 0.26.11`, OpenCLIs build `2026-07-21-154218`. Run `kernel-cli --version` and `kernel-cli --help` for the installed contract on your machine.* Direct Kernel CLI use is **raw capability**. Write commands execute immediately; there is no NIIA approval gate in front of them. Use the NIIA harness when a human must authorize control. ## Quick Start ```bash theme={null} openclis install kernel-cli kernel-cli --version kernel-cli --json doctor kernel-cli --json snapshot kernel-cli docs agent-flow ``` `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 --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: ```bash theme={null} openclis init kernel-cli OPENCLIS_NEXT=1 openclis kernel-cli targets --app "TextEdit" ``` The wrapper preserves the native result and appends command-specific next steps for MCP, websurf, chat, verified input, targets, click, URL, act, capture, and docs. It does not replace Kernel CLI's invocation-local `[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: ```text theme={null} App data and machine state ↓ Windows, sessions, and accessibility ↓ Targets with stable handles ↓ Rendered-text OCR ↓ Screenshots and coordinates ``` The same ordering applies to control: ```text theme={null} App-native action ↓ Accessibility press / set / menu / target action ↓ Keyboard input in a verified context ↓ Pointer or device-level fallback ``` This does not remove pixel automation. It keeps pixels as evidence and fallback instead of making every workflow begin with an image and a coordinate guess. ## Seven Capability Surfaces Read snapshots, windows, displays, accessibility trees, actionable targets, rendered text, app data, logs, and reactive wait/watch conditions. Act on target handles, press or set accessible elements, type, send keys, control apps and windows, use menus, and fall back to pointer input. Inspect processes, hardware, CPU, power, devices, ports, routes, proxy, security posture, services, schedules, backups, logs, and session state. Use `kernel-cli websurf` for DOM, JavaScript, CDP, persistent browser profiles, site plugins, feed collection, and browser QA. Ingest WhatsApp text or ZIP exports, then list, read, search, measure reply latency, and export the canonical conversation through `kernel-cli chat`. Execute a multi-step keyboard plan once, then observe stable application state before moving to the next step. 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: 1. Observe structured state with `snapshot`, `windows`, `ax-tree`, or `targets`. 2. Resolve a semantic target and keep its `snapshot_id` and `target_id`. 3. Preview the write with `act --dry-run`. 4. Act only after the target and backend are clear. 5. Read back the resulting state before trying a fallback. ```bash theme={null} kernel-cli --json targets --app "TextEdit" --intent save --top 20 kernel-cli --json act '' --snapshot '' --dry-run ``` The snapshot guard refuses stale state instead of silently applying an old handle to a changed UI. See [Workflows](/kernel-cli/workflows) for the complete direct and NIIA-gated loops. ## 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: | Surface | Guidance contract | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | Human CLI | The dynamic emitter appends at most one `[NEXT]` block on stderr. Binding rows add `[IAW-SOP]`; `ORDER` rows number the required sequence. | | CLI with `--json` | Stdout remains the command's structured result; stderr receives one `[NEXT] {json}` line with stable `id` and `sop` fields. | | Native MCP | The same object is returned as `structuredContent.guidance`; error results retain their existing `try_next` field. | 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.11 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.11 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: | `sop` | Meaning | | ---------- | ----------------------------------------------------------------------------------------------- | | `order` | `[NEXT] [IAW-SOP] ORDER` is a numbered chain; execute every step top-to-bottom. | | `route` | `[NEXT] [IAW-SOP]` names the surface that owns the state; do not continue on a competing route. | | `advisory` | Plain `[NEXT]` remains a situational recommendation. | 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.26.11 gives 32 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: | Layer | Owns | Approval behavior | | -------------- | ---------------------------------------------------------- | --------------------------------------------- | | `kernel-cli` | Raw OS observation, control, telemetry, CLI, and MCP tools | Direct writes are immediate | | `niia observe` | Read-only harness surface | Read-only command set | | `niia control` | Human-controlled write surface | OTP unlock, time-limited scope, explicit lock | 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](/monosurf/index) and the embedded namespace therefore use one canonical help surface, embedded documentation tree, profile TUI, planner, and runtime: ```bash theme={null} kernel-cli websurf --help kernel-cli websurf browse https://example.com --extract kernel-cli websurf browse --cdp-url http://127.0.0.1:9222 ``` The embedded and standalone commands share browser profiles, plugins, grants, and state under `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](/monosurf/usage) for the complete compatibility surface and Kernel CLI for browser chrome, native dialogs, and other OS UI. Kernel CLI 0.26.11 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.11 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.11 has 111 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. ## Embedded Chat Reader ```text theme={null} app pack exports a chat ──▶ kernel-cli chat ingest ──▶ shared chat store │ list · read · search · stats · timeline · export ``` `kernel-cli chat` is the read side of the app-pack flow. The WhatsApp `export-chat` gesture produces the original text or ZIP export; the embedded reader parses it on demand without inventing participants, reactions, or timestamps. It shares its core and store with standalone `monochat`, so no second installation is needed on a machine that already has Kernel CLI. ```bash theme={null} kernel-cli chat ingest ~/Downloads/"WhatsApp Chat - Team.zip" kernel-cli chat list kernel-cli chat search team "release date" --json kernel-cli chat timeline team --reply-latency kernel-cli chat export team --format md ``` See [Chat Exports](/kernel-cli/chat) for format detection, chronology guards, storage, and the current WhatsApp-only adapter boundary. ## Verified Input Transactions ```text theme={null} preflight → settle app → read before → post once → observe → stable → VERIFIED └──────────── refuse ────────────────────────────────┬──────→ TIMEOUT └──────→ ERROR ``` The `input` command executes a `kernel.input.plan.v1` file. Each mutation is posted at most once; verification observes the result instead of retrying the keystroke. A step can require exact value, suffix, focus-change, or focus-match postconditions and returns `POSTED`, `OBSERVED`, `VERIFIED`, `TIMEOUT`, `REFUSED`, or `ERROR` as evidence rather than treating event delivery as task completion. ```bash theme={null} kernel-cli input --file save-form.json --json kernel-cli input --file - --json < save-form.json ``` See [Verified Input](/kernel-cli/verified-input) for the plan schema, clipboard/focus leases, and safe failure behavior. ## 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 ` 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: ```bash theme={null} kernel-cli collection list kernel-cli collection search whatsapp kernel-cli collection show whatsapp kernel-cli collection install whatsapp kernel-cli collection update ``` An install verifies the profile SHA-256 against the CDN index, validates the same format used by local profiles, discloses code-bearing `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 ` 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: ```bash theme={null} kernel-cli window --id 12582969 focus # decimal or 0x-prefixed id kernel-cli menu status --app Safari # macOS readiness/residue diagnosis kernel-cli menu close --app Safari # macOS manual residue recovery ``` `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 `. 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: ```text theme={null} observe structured state → choose a semantic target → act → verify → fall back ``` The backend is platform-specific: * **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. Do not treat a platform name as proof that a feature is ready. `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: ```bash theme={null} kernel-cli mcp ``` The MCP server exposes 116 tools in version 0.26.11. It mirrors all 111 normalized CLI command names and adds the MCP-native or compatibility tools `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 Install, diagnose, observe, dry-run, act, verify, and use the NIIA harness. Command families, platform boundaries, permissions, MCP setup, and operations. Ingest, inspect, search, measure, and export human conversation archives. Execute keyboard plans once and prove stable application state afterward. Learn the complete command surface shared by standalone MonoSurf and the embedded `kernel-cli websurf` namespace. Why raw capability and human authorization are separate layers. Install the OpenCLIs package manager before installing Kernel CLI.