Skip to main content
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:
This page was verified against kernel 0.26.8, OpenCLIs build 2026-07-19-224153.

Complete Command Reference

Read what every one of the 109 commands does, including its important actions, options, and runtime boundaries.

Browser Automation with MonoSurf

Use the same CDP engine through kernel-cli websurf or the standalone MonoSurf entry point.

​
Command Families

This table is the compact map. The Complete Command Reference enumerates all 109 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.8 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:
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 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.8 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.

​
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/.
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 <path-or-url> 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 <app> for frame-bound packs; no badge means the pack is size-free.

​
Exact Windows and Menu Residue

window --id <decimal|0xhex> <action> 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 <app>. 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:
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. For targets, the precedence introduced in 0.24.9 remains the 0.26.8 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: Version 0.24.11 adds one evidence-gated non-browser route: Every object has this stable shape:
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.8 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.8 applies that classification centrally across CLI and MCP errors while preserving the one-emission guard.

​
Health and Capability Truth

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

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

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

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:
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:
The embedded pages travel with the executable and provide deeper operating and platform notes. Use the Complete Command Reference 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:
Client configuration:
Version 0.26.8 exposes 114 MCP tools: all 109 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.8 before using an MCP client’s safety hints or audit trail for collection writes.
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:
Recording is not video capture. Use a separate visual recorder when the proof must include pixels as well as tool calls.

​
Install and Update

Build 2026-07-19-224153 is the Kernel CLI 0.26.8 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 2e4b71d96b98923a651fe1cfc1b344bfa60dfec1 with source_dirty: false. The immutable kernel-cli-v0.26.8 tag points to that commit and main contains the tag, so the pointer, five platform witnesses, and release source agree. 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 24 source-owned initiate files plus generated initiate.json, for 25 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.8 and embedded monosurf 0.11.3; the checked surface is 109 root commands and 114 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.8 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. Main/public registry commit ade36c68f9d2e7cc1982b4412105e933317d6fe9 records this post-tag documentation correction; it does not change release artifact provenance. Version 0.26.2 remains superseded because of its unsafe collection MCP metadata. Update 0.26.2 or 0.26.3 installations to 0.26.8. 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 for the recommended observe/dry-run/act/ verify loop and NIIA-gated control.