> ## 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 Reference > Kernel CLI command families, structured output, platform behavior, permissions, health checks, audit, embedded docs, updates, and MCP setup. This page maps the public command families and operating boundaries. Kernel CLI evolves quickly, so the installed binary remains the authoritative command and option reference: ```bash theme={null} kernel-cli --version kernel-cli --help kernel-cli --help ``` *This page was verified against `kernel 0.26.11`, OpenCLIs build `2026-07-21-154218`.* Read what every one of the 111 commands does, including its important actions, options, and runtime boundaries. Use the same CDP engine through `kernel-cli websurf` or the standalone MonoSurf entry point. ## Command Families | Family | Representative commands | Purpose | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | UI observation | `snapshot`, `windows`, `displays`, `ax-tree`, `elements`, `targets`, `read`, `url` | Read the live desktop as structured state | | Web-page automation | `websurf` | Read and drive DOM, JavaScript, CDP endpoints, profiles, plugins, feeds, network evidence, and browser QA through the embedded `lib-monosurf` facade and `lib-monosurf-core` engine | | Conversation data | `chat` | Ingest WhatsApp exports, then list, read, search, measure, and export them through the embedded monochat reader | | Pixel observation | `read-text`, `read-barcodes`, `capture`, `wait` | Read rendered or visual-only surfaces | | Reactive observation | `ax-watch`, `watch`, `logs --follow`, `monitor` | Observe bounded live changes and events | | Machine state | `report`, `hardware`, `devices`, `stats`, `power`, `cpu`, `process`, `session`, `security` | Diagnose the computer itself | | Network and services | `ports`, `netusage`, `network`, `route`, `proxy`, `services`, `schedule`, `backup`, `logs` | Inspect connectivity and background work | | Semantic control | `act`, `ax-press`, `ax-set`, `ax-select`, `menu` | Change named or handled UI elements | | Input and windows | `input`, `type`, `key`, `paste`, `click`, `click-text`, `scroll`, `drag`, `window`, `app` | Drive text, pointer, app, and window state; strict input plans bind steps to observable postconditions | | App-profile automation | `gesture`, `profile`, `collection`, `config` | Discover, run, distribute, rebaseline, and focus-govern reusable app actions | | System writes | `clipboard`, `defaults`, `open`, `shortcut`, `notify`, `display`, `bluetooth`, `brightness`, `audio`, `volume`, `lock` | Change OS-level state explicitly | | Operations | `doctor`, `permissions`, `docs`, `config`, `audit`, `undo`, `trace`, `record`, `replay`, `mcp` | Diagnose, document, audit, and integrate the tool | This table is the compact map. The [Complete Command Reference](/kernel-cli/commands) enumerates all 111 commands and their public behavior. Running `kernel-cli --help` remains the exact syntax check for the installed version. ## Browser Boundary: MonoSurf Kernel CLI 0.26.11 embeds the `lib-monosurf 0.11.3` facade and `lib-monosurf-core` engine. It shares the profile registry, plugins, grants, planner, runtime state, canonical help, embedded docs, and profile TUI with standalone MonoSurf 0.11.3. The executables are independently published and not byte-identical, but expose the same current page-automation contract. The page and operating-system capability boundaries remain distinct: | Surface | Owns | Typical work | | --------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `kernel-cli websurf` or [MonoSurf](/monosurf/index) | The Chromium page visible through the shared `lib-monosurf` facade and `lib-monosurf-core` engine | DOM/forms, JavaScript, persistent login profiles, external CDP attach, feed collection, page network capture, screenshots, console and selector assertions | | Kernel CLI OS commands | The operating system and native desktop | Browser chrome, native dialogs, permission prompts, accessibility, OCR, keyboard/pointer input, windows, and non-browser apps | ```text theme={null} kernel-cli websurf / MonoSurf works inside the page ↓ native dialog or browser chrome appears ↓ Kernel CLI completes the OS interaction ↓ MonoSurf returns to the page and verifies ``` For example, the shared web surface can activate a page's upload control, but the resulting operating-system file picker is outside CDP. Kernel CLI resolves and completes that native picker, then the web surface waits for and verifies the uploaded state in the page. See the [MonoSurf Usage and Command Reference](/monosurf/usage) for the complete shared compatibility surface and handoff boundary. Both entry points use the same profile registry, site plugins, grants, and browser state under `Application Support/Monolex/monosurf/`. Standalone `monosurf` is not required by `kernel-cli websurf`; it is an independently published thin frontend over the same facade and engine. The embedded command runs in-process and never launches the standalone executable. Managed profiles skip active unregistered ports and verify ownership on the exact port selected for launch. Foreign ownership is refused immediately; temporarily unknown OS metadata receives only a bounded settle interval before the command fails closed. Explicit `--cdp-url` remains the intentional foreign attach path and never transfers lifecycle ownership. Cookie bridge import is narrower than same-profile reuse. `websurf bridge install` materializes the fixed-ID extension, copies the existing Monolex shared native host under its MonoSurf routing name, and writes the manifest; `bridge [domain] [--keep]` accepts explicit Sync clicks. The prerequisite is `~/.niia/bin/monolex-native-host` staged by Monolex desktop (`.exe` on Windows). The Kernel CLI 0.26.11 archive does not bundle it, so absence is a non-zero installation failure even if extension assets were materialized first. Before navigation, only an empty live jar can be hydrated, with an explicit origin and preserved cookie attributes. Invalid scope or any CDP error aborts the command. This route does not copy localStorage, IndexedDB, service workers, passwords, the daily Chrome profile, or its process. The Monolex Agent Browser's managed-login route is the separate same-profile path for complete browser state. ## Chat and Verified Input Boundaries `chat` reads exported human conversations; it does not automate the source app. The app profile is the producer, the text or ZIP export is the handoff, and the embedded monochat reader is the consumer. Kernel CLI and standalone `monochat` share one local store. In 0.26.11, only WhatsApp text exports are supported and the `chat ingest` audit hook remains a disclosed gap. See [Chat Exports](/kernel-cli/chat). `input` owns ordered keyboard plans. It posts each action once and then waits for a stable accessibility postcondition. `POSTED` is not `VERIFIED`; strict failures return non-zero without retrying the mutation. Clipboard and focus are restored only while Kernel CLI still owns the staged state. See [Verified Input](/kernel-cli/verified-input). ## App Profiles and Kernel Collection `profile` owns local per-app action dictionaries; `gesture` runs one named action; `collection` owns discovery and distribution of curated dictionaries. The unit on disk remains a normal profile under `~/.kernel-cli/profiles/`. ```bash theme={null} kernel-cli profile describe WhatsApp --json kernel-cli profile rebaseline Blender kernel-cli gesture orbit --app Blender --by 120,40 --conform kernel-cli collection show whatsapp kernel-cli collection install whatsapp kernel-cli collection update ``` Version 0.25.0 records a profile's authored window/display geometry. Absolute coordinate gestures check size and position, relative gestures check size, and semantic AX/key/menu gestures skip geometry checks. A mismatch warns by default; `--conform` moves or resizes before control, while `rebaseline` adopts the live frame without discarding unknown profile fields. Parameter `hints` close value-domain gaps in `profile describe` output. Version 0.26.0 adds six collection actions: `list`, `search`, `show`, `install`, `update`, and owner-side `publish`. Installation verifies the CDN index hash, validates the profile, discloses code-bearing steps, and re-centers a foreign geometry context on the local main display. A receipt protects locally edited or hand-authored profiles from replacement unless `--force` is present; `install --from ` follows the same validation pipeline. The current collection inventory exposes size sensitivity before execution: `[frame-bound N]` counts absolute-coordinate gestures tied to the authored window frame, while `[size-scaled N]` counts relative drags whose feel changes with window size. `collection show` prints the same geometry summary. Use `--conform` or `profile rebaseline ` for frame-bound packs; no badge means the pack is size-free. ## Exact Windows and Menu Residue `window --id ` targets the exact identifier returned by `windows`; it conflicts with `--title`, preventing one invocation from naming two possible windows. Linux app launch and focus settle against the accessible desktop object before success is reported. On macOS, normal menu invocation cleans up AX-opened residue. `menu status [--app X]` diagnoses readiness and residue, while `menu close [--app X]` is the manual recovery route. Cleanup failure is visible rather than silently leaving an open menu behind. Version 0.26.1 turns profile-authored guidance into output. A profile-level `note` explains the full pack, with legacy `_note` accepted as an alias; gesture-level `note` and `next` fields explain one verb and its follow-ups. `profile describe` shows those fields, JSON preserves the complete pack note, and a successful `gesture` returns its parameter-resolved `next` array or a human `[NEXT] declared by the profile:` block. Intent and focus badges remain engine-derived, so prose supplied by a profile cannot promote its capability. Focus is a separate safety dimension. Profiles can declare `none`, `require`, or `yield`; machine defaults configure `on_busy`, `busy_threshold_secs`, `yield_timeout_secs`, and `restore`. In 0.26.1, a busy macOS yield races three signals: OK consents immediately, Cancel/Esc returns a class-tagged `focus_busy` refusal, and pausing input satisfies the HID-idle handoff. Cancel is the default button. Other platforms, or an unavailable dialog process, use the bounded notification-plus-idle fallback. `--restore-focus` returns only the focus that the gesture itself took. A gesture chain needs a stronger contract: read `frontmost` before the first process, then pass that app to the last process with `--restore-to `. The explicit target implies restore and wins over per-process auto-capture; because it activates unconditionally, the caller must preserve the human's intended original app. The atomic `paste_via_menu` step restores the previous clipboard value after menu-backed text entry. ## Structured Output Most read and action commands support `--json`: ```bash theme={null} kernel-cli --json doctor kernel-cli --json targets --top 20 kernel-cli --json report ``` Use structured output when an agent must preserve ids, snapshot guards, capability state, or typed values. Human output is optimized for inspection; JSON is the contract for automation. ### Result-guided routing Version 0.24.8 adds a versioned guidance catalog. A routed CLI result keeps its normal stdout and appends at most one `[NEXT]` recommendation on stderr. Human mode renders a reason plus commands; `--json` mode renders one compact JSON object after the marker. Native MCP inserts the identical object at `structuredContent.guidance`. | Result family | Stable guidance ids | | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | Capability probe | `doctor.ax_ready`, `doctor.ax_unavailable` | | App accessibility | `app.accessibility_ready`, `app.accessibility_shallow` | | App-pack routing | `app.pack_available` | | Semantic discovery | `targets.actionable`, `targets.empty`, `targets.browser_shallow`, `ax_tree.empty`, `ax_tree.webview_content`, `elements.empty` | | Target action and recovery | `act.verified`, `act.stale`, `act.offscreen`, `act.target_not_found`, `targets.ambiguous` | | OCR and coordinates | `read_text.matches`, `ocr.structured_value_untrusted`, `ocr.low_confidence`, `read_text.empty`, `coordinate.unanchored`, `coordinate.into_browser` | | Route selection | `script.gui_context`, `url.websurf_eligible`, `url.native_unreadable`; MCP `docs.topic_unknown`; catalog-only `websurf.native_dialog` | | Runtime recovery | `error.permission`, `error.wrong_app_or_focus_lost` | For `targets`, the precedence introduced in 0.24.9 remains the 0.26.11 behavior: any AX handle → `targets.actionable`; otherwise structured OCR → `ocr.structured_value_untrusted`; otherwise low-confidence OCR → `ocr.low_confidence`; otherwise any remaining target → `targets.actionable`; otherwise `targets.empty`. This precedence is shared by CLI and MCP. Version 0.24.10 specializes three routes only from invocation-local browser facts: | Guidance id | Evidence required | Boundary it preserves | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `targets.browser_shallow` | `targets`, `elements`, or `ax-tree` was scoped to a Chromium-family app and returned no semantic evidence. | Use `websurf` for the page DOM, or relaunch with renderer accessibility before retrying native AX. | | `coordinate.into_browser` | The click carried an enforced `--expect-app` browser pin, or a browser-scoped skylight window resolve. | Page DOM returns to `websurf`; browser chrome and native dialogs remain native Kernel CLI work. | | `url.native_unreadable` | URL lookup confirmed a browser surface but accessibility exposed no URL. | Copy the address bar explicitly or read page state through `websurf`; do not trust OCR URL bytes. | | `websurf.cdp_endpoint_gone` | An intentional `--cdp-url` attach no longer answers because the browser exited or relaunched without its debugging port. | Stop retrying the dead endpoint; use a managed websurf browser, verify the live browser through native AX, or relaunch accessibly while preserving runtime flags. | Version 0.24.11 adds one evidence-gated non-browser route: | Guidance id | Evidence required | Boundary it preserves | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | | `ax_tree.webview_content` | An explicit non-browser `--app` scope returned a non-empty tree containing a web-area subtree, and the caller did not already pass `--web-depth`. | Descend through AX with `--web-depth`; do not attempt `websurf`/CDP attach to an app webview. | Every object has this stable shape: ```json theme={null} { "v": 2, "id": "doctor.ax_ready", "phase": "observe", "sop": "advisory", "reason": "...", "next": ["kernel-cli --json targets --top 20 # actionable handles first"], "avoid": ["coordinate-first"], "docs": "agent-flow", "confidence": "known" } ``` Every route is invocation-local. Its `sop` value is `order`, `route`, or `advisory`: ORDER rows are numbered binding sequences, route rows bind surface ownership, and advisory rows remain optional. Guidance never performs another probe, changes the primary result or exit code, grants a capability, or infers what a previous process observed. Ambiguous internal states emit nothing. MCP uses `docs.topic_unknown` for an invalid conceptual topic. `websurf.native_dialog` is catalogued for a future positive page-to-native handoff signal, but version 0.26.11 does not emit it from a generic CLI or MCP web call. MCP error results keep their existing `error`, `class`, and `try_next` fields and add `guidance` only when the error class has a specific recovery route. Version 0.26.11 applies that classification centrally across CLI and MCP errors while preserving the one-emission guard. ## Health and Capability Truth ```bash theme={null} kernel-cli doctor kernel-cli --json doctor ``` `doctor` reports runtime facts, not a static support claim. It separates capabilities such as accessibility, capture, OCR, protected-data reads, input, background clicks, scripts, kernel events, and real HID. An unavailable capability is accompanied by its requirement and remediation. The same OS can report different results across a logged-in desktop, a remote session, a headless shell, or a service context. ## Platform Behavior | Platform | Primary UI surface | Important runtime boundary | | -------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | macOS | Accessibility, CoreGraphics, Vision, and native system frameworks | Accessibility, Screen Recording, Full Disk Access, Automation, and optional HID approval are feature-specific | | Linux | AT-SPI plus X11/Xwayland or desktop helper tools | Desktop bus, display server, helper installation, and compositor policy determine live support | | Windows | UI Automation, Win32, and Windows OCR/system APIs | GUI control requires the interactive user desktop; OCR depends on language support | The cross-platform contract is behavioral: observe, resolve, act, verify, then fall back. It does not mean every operating system uses the same backend or offers every capability in every session. ### Linux setup ```bash theme={null} kernel-cli docs linux-setup kernel-cli docs platform-command-checklist ``` The embedded Linux guide contains the current package-to-command map and verification commands. Use it instead of copying an old dependency list from a web page. ## macOS Permissions ```bash theme={null} kernel-cli permissions kernel-cli permissions open ``` | Permission | Typical owners | | ------------------- | ------------------------------------------ | | Accessibility | AX reads/actions and synthetic input | | Screen Recording | Screenshots, OCR, and barcode capture | | Full Disk Access | Protected app databases and some log reads | | Automation | AppleScript/JXA access to a target app | | VirtualHID approval | Optional device-level input with `--real` | Permissions are attributed to the process identity that performs the work. A permission granted to one terminal, app, or daemon does not automatically prove that another identity is authorized. ## Safety and Audit Direct Kernel CLI execution has no NIIA permission gate. Mutating commands are recorded in a local audit file by default: ```bash theme={null} kernel-cli audit --limit 20 kernel-cli audit --path ``` The global `--no-audit` option can suppress that local record. An audit log is evidence after the fact; it does not approve or block the action. Use `niia control` or another harness when authorization must happen before a write. ## Embedded Documentation Kernel CLI ships its detailed operating docs inside the binary: ```bash theme={null} kernel-cli docs kernel-cli docs agent-flow kernel-cli docs observe kernel-cli docs control kernel-cli docs permissions-safety kernel-cli docs computer-use-web-apps kernel-cli docs linux-setup kernel-cli docs platform-command-checklist ``` The embedded pages travel with the executable and provide deeper operating and platform notes. Use the [Complete Command Reference](/kernel-cli/commands) for the public capability map, the installed command's `--help` for exact syntax, and `doctor` for live runtime availability. ## MCP Server Start the stdio MCP server with: ```bash theme={null} kernel-cli mcp ``` Client configuration: ```json theme={null} { "mcpServers": { "kernel-cli": { "command": "kernel-cli", "args": ["mcp"] } } } ``` Version 0.26.11 exposes 116 MCP tools: all 111 normalized CLI command names plus `computer_use`, `health_report`, `connections`, `trackpad`, and `type_text`. The `collection` tool contains read and write actions in one schema, so its static annotations reflect its strongest operation: it is not read-only or idempotent, it is destructive and open-world, and it advertises `tooling.control`, `network.read`, and `network.write`. Runtime accountability remains action-aware: `install`, `update`, and `publish` are audited and may be recorded, while the default/list, search, and show paths are excluded from the mutating trajectory. The server includes three complementary shapes: Kernel CLI 0.26.2 exposed `collection` through MCP but advertised the default read-only metadata inherited by an unmapped tool. Update to 0.26.11 before using an MCP client's safety hints or audit trail for collection writes. | Shape | Use it when | | ----------------------- | ---------------------------------------------------------------------------------------------------- | | Raw typed tools | You need the full Kernel CLI command surface, exact diagnostics, or direct OS capabilities | | `computer_use` facade | The client expects one capture/action loop with structured elements and reusable handles | | `websurf` typed adapter | You need redaction-safe effect planning, browser/profile discovery, or a typed site-plugin operation | The facade is a compatibility surface over Kernel CLI. It offers a familiar usage shape without replacing the raw tools or implying shared implementation lineage with another computer-use driver. Use MCP `health_report` before relying on a tool. It reports permission and capability state in machine-readable form and returns the matching AX route as `structuredContent.guidance`. MCP `help` returns the golden-flow instructions, the live tool inventory, and explicit next actions. The MCP `docs` tool returns conceptual text plus the discovery `next` list. The MCP `websurf` operations are `plan`, `browsers`, `profiles`, and `site`. They do not reproduce every terminal flag; use `kernel-cli websurf` for the complete command-compatible page automation surface. ## Recording and Replay MCP trajectory recording captures mutating tool calls for audit and controlled replay: ```bash theme={null} kernel-cli record status kernel-cli record start kernel-cli record stop kernel-cli replay ``` Recording is not video capture. Use a separate visual recorder when the proof must include pixels as well as tool calls. ## Install and Update ```bash theme={null} openclis install kernel-cli openclis update kernel-cli kernel-cli --version ``` Build `2026-07-21-154218` is the Kernel CLI 0.26.11 release train. Its public metadata contains five archives: Apple Silicon macOS plus x86-64 and ARM64 payloads for Linux and Windows. There is no Intel macOS artifact in this path. `latest.json` and every platform entry record clean source commit `85db004393655fed4455f038ad6d0958abaf6021` with `source_dirty: false`. The immutable `kernel-cli-v0.26.11` tag points to that commit and main contains the tag, so the pointer, five platform witnesses, and release source agree. | Platform id | Archive SHA-256 | Extracted payload SHA-256 | Format and runtime witness | | ----------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- | | `darwin-aarch64` | `a7ade29fb7ce95381f0a824dee6865707fbea9aaa6122cb6258664582998b2cd` | `e0f2c02fd8f68217d7a91ac95d4793f77646ccd92ac25a06dfc9fb19b92eca56` | Mach-O arm64; OpenCLIs-installed payload executed and passed strict Developer ID verification | | `linux-x86_64` | `c9da6d986a233d48db55819474abfb48a47f5dcca1d2b236487fbce6a0dcc5ca` | `974b6b9e1acb600bcf9fe15ef8fe77c9b52911f89922b6b38dcaadf8b2f6d6f2` | Statically linked x86-64 ELF with the complete release guide bundle | | `linux-aarch64` | `afab80af571a8af6025d883a758597d05516bf903753249492d6b94ad292c7d6` | `617a9a6899cb72708a5141cad87f05638e0cc3163a569dc8d8a4eaefb6c2937b` | Statically linked AArch64 ELF with the complete release guide bundle | | `windows-x86_64` | `28dcd99fd326e4add5534073120b0ded7ffeef9f9ef11ebe374bc46420fd1417` | `4e25dc0523ba92ad13afcadd91b718b4abc288c102d13bf32e18246eac3bcbf1` | PE32+ x86-64 with the complete release guide bundle | | `windows-aarch64` | `33ac3a05424a34d806f34d0196cd448468678012ab2d121046b705ea61fbad50` | `11e99fc526c7b6079582b43dcc8859ece04beb220a789343c8273754b03bd74e` | PE32+ AArch64 with the complete release guide bundle | The installed macOS payload is signed by `Umzikim Inc (64RS2P6LN2)`, passes strict Developer ID verification, and `spctl --assess --type install` accepts it as `Notarized Developer ID`. The Windows x86-64 payload has no Mark-of-the-Web stream and reports Authenticode `NotSigned`, but the exact verified hash ran successfully on a Windows 11 host with `VerifiedAndReputablePolicyState = 1`. Publication, archive integrity, Authenticode status, and host execution policy are separate proof layers; unsigned does not mean unpublished. Every archive contains the 28 source-owned `initiate` files plus generated `initiate.json`, for 29 guide files whose text matches the tagged source after normalizing Windows line endings. Installed macOS, Windows x86-64, and Linux x86-64 runtimes report `kernel 0.26.11` and embedded `monosurf 0.11.3`; the checked surface is 111 root commands and 116 MCP tools. Bridge installation has one external prerequisite: the `~/.niia/bin/monolex-native-host` staged by Monolex desktop (`.exe` on Windows). The Kernel CLI 0.26.11 archives do not bundle it. With an otherwise empty home, `bridge install` returns non-zero after reporting `shared native host not found`, even though unpacked extension assets may already exist. Version 0.26.2 remains superseded because of its unsafe `collection` MCP metadata. Update older installations to 0.26.11. Keep proof layers separate when checking a release: 1. Source documentation describes a capability. 2. The registry publishes a version and build. 3. OpenCLIs installs a particular artifact. 4. `kernel-cli --version` proves which binary runs. 5. `doctor` proves what that binary can do in the current session. See [Workflows](/kernel-cli/workflows) for the recommended observe/dry-run/act/ verify loop and NIIA-gated control.