Skip to main content
Kernel CLI works best as a short evidence loop: inspect the live machine, choose the strongest available target, preview the write, act once, and verify. Verified against kernel 0.26.8, OpenCLIs build 2026-07-19-224153.

​
1. Install and Prove the Binary

The four outputs prove different things: Use openclis update kernel-cli to update an existing installation.

​
2. Follow the Live Routing Contract

The bare command prints the full live agent reference. --help is the concise inventory, command help owns exact syntax, and docs agent-flow owns the DOM/AX/OCR/coordinate routing model. Selected results append one [NEXT] recommendation on stderr. Keep stdout and stderr separate in automation: JSON stdout is still the primary result, while the stderr line beginning [NEXT] is a versioned guidance object. In MCP, read the same object from structuredContent.guidance; mapped error results also retain their established try_next list. Treat guidance as an evidence-backed route, not a second result. Version 0.26.8 retains three sop levels:
  • order: [NEXT] [IAW-SOP] ORDER is a numbered sequence. Execute every step top-to-bottom.
  • route: [NEXT] [IAW-SOP] binds which surface owns the state. Do not keep working through a competing surface.
  • advisory: plain [NEXT] remains optional.
Every row is based only on the current invocation and never changes the exit code or grants a missing capability. Classified failures use the same central catalog even when the individual command branch has no local emitter.

​
3. Observe Before Acting

Start broad, then narrow:
targets combines accessible controls with rendered-text targets where the platform supports them. Its JSON includes the current snapshot_id, target handles, labels, roles, and preferred write paths. Since version 0.24.9, AX targets remain usable when optional OCR fails. In a mixed result, any AX handle also keeps the next route on semantic action even if OCR fallbacks report structured or low-confidence values. When neither backend returns evidence, the command still fails instead of presenting an empty map as success. In 0.24.10, a Chromium-scoped empty targets, elements, or ax-tree result emits targets.browser_shallow. Follow its boundary deliberately:
A coordinate click emits coordinate.into_browser only when this invocation verified a Chromium-family target through --expect-app or a browser-scoped skylight resolve. If url --app <browser> confirms the browser but cannot read the address through accessibility, url.native_unreadable recommends explicit address-bar copy or websurf; it never promotes an OCR transcription to the canonical URL. In 0.24.11, a non-browser desktop app can expose an embedded webview through its accessibility tree. When an explicit --app scope contains a web-area subtree and you did not already request --web-depth, the result emits ax_tree.webview_content:
Do not substitute websurf --cdp-url unless the application independently exposes a real CDP endpoint.
Read-only does not mean non-sensitive. Snapshots, accessibility trees, OCR, clipboard data, app databases, logs, and screenshots can expose private data.

​
4. Preview the Write

Copy a target_id and the owning snapshot_id from targets, then resolve the planned action without actuating it:
The preview reports the resolved target and selected backend. If the UI changed, the snapshot guard refuses the stale handle. For a non-destructive visibility check, reveal the target instead of activating it:

​
5. Act Once, Then Read Back

When the preview is correct:
Then verify through the surface that owns the result:
  • Re-run targets or ax-tree for an accessibility change.
  • Use read for a focused text field.
  • Re-run windows for window geometry or focus.
  • Use read-text for rendered text that accessibility cannot expose.
  • Use capture only when visual evidence is the right proof.
Do not send a coordinate fallback after a semantic action already succeeded. Read back first; otherwise the same user intent may be applied twice.

​
6. Diagnose the Machine, Not Just the UI

Many desktop failures are actually permission, process, session, network, or resource problems. Kernel CLI keeps those facts on the same surface:
Use these reads before assuming that a missing window or failed action is an application bug.

​
7. Fall Back Deliberately

Use the next layer only when the previous layer cannot describe the target:
Pointer commands, private background-click paths, and device-level HID are powerful fallbacks. They are not the default because they carry weaker semantic guarantees than named actions and target handles.

​
8. Install and Run an App Profile Deliberately

Inspect a curated profile before installing it, then inspect the installed gesture contract before running a write:
The collection installer verifies the index SHA-256, validates the profile, discloses code-bearing steps, and writes an install receipt. A later update skips locally modified content unless --force is explicit. For a coordinate-sensitive profile, resolve frame drift rather than ignoring it: Before installation, collection list and collection show display [frame-bound N] for absolute-coordinate gestures and [size-scaled N] for relative drags. Use --conform or profile rebaseline for frame-bound packs; a pack without either badge is size-free. In 0.26.1, the JSON description also returns the pack’s full note and each gesture’s note and next array. Treat those as author-declared usage and follow-up guidance, while keeping the engine-derived intent and focus tags as the capability boundary. After a successful gesture, consume the resolved next array in JSON or the [NEXT] declared by the profile: block in text.
--conform applies the recorded geometry for this run; rebaseline changes the profile’s recorded context to the current frame. For foreground-taking gestures on a shared desktop, use the 0.26.1 focus policy:
On macOS, --yield opens a visible handoff dialog while the human is active: OK consents immediately, Cancel/Esc refuses, and pausing input lets the idle threshold complete the handoff. Cancel is the default. Other platforms, or a failed dialog launch, use notification plus the same bounded idle wait. --restore-focus gives back only the focus that the gesture itself acquired. That automatic capture is process-local. For a chain of separate gesture processes, capture the user’s app once and restore it explicitly on the last gesture:
--restore-to <app> implies restore and activates the named app unconditionally. Use it only with a target captured before the chain; unlike --restore-focus, it intentionally does not preserve a third app that the human moved to while the chain was running. For OCR outside a profile, scope pixels to the owning app or exact window with read-text --app/--window and click-text --app/--window.

​
9. Import a Chrome Login Without Blending Session Models

Use the bridge only when an explicit cookie snapshot is sufficient:
Prerequisite: Monolex desktop must have staged ~/.niia/bin/monolex-native-host (.exe on Windows). The Kernel CLI 0.26.8 archive does not bundle this shared host. If it is absent, bridge install returns non-zero even though extension assets may have been materialized; stage the host through Monolex desktop and rerun before loading the extension. Load the printed unpacked extension directory in Chrome, open the logged-in target tab, then click Sync. The receiver stores only cookies for the active tab. Before a later site command navigates, MonoSurf checks the live jar and hydrates only when it is empty. Cookie scope is validated, an explicit HTTP(S) origin is supplied, domain/path/HttpOnly/Secure/SameSite/expiry are preserved, and any CDP error aborts the command. This is not daily-Chrome remote control and not a profile clone: localStorage, IndexedDB, service workers, passwords, the Chrome process, and unrelated tabs are not copied. A non-empty live jar wins. For complete state, use the Monolex Agent Browser’s managed Sign In with Chrome → Open in Agent same-profile path instead. New managed profiles skip active unregistered CDP ports, then prove ownership on the exact chosen port before their record is committed. --cdp-url remains the explicit externally owned attach route. Bind a critical click to its evidence in one command:
Use postcondition toast --toast <selector> [--toast-text <text>] when success is a visible toast and the URL intentionally stays unchanged. Ambiguous controls, URL drift, hidden/covered targets, missing evidence, and timeouts all fail closed.

​
10. Target One Window or Recover a Menu Explicitly

window --id accepts decimal or 0x-prefixed identifiers and conflicts with --title. On macOS, menu actions normally clean their own AX-opened residue; status is the diagnostic and close [--app X] is manual recovery. Linux app launch/focus waits for accessible matching and focus settlement before success.

​
11. Use the NIIA Harness for Human-Gated Control

NIIA exposes a read-only observe surface and an OTP-gated control surface over Kernel CLI capabilities:
The agent should never self-unlock. The human completes the OTP step; the harness controls the scope and duration.

​
12. Connect an MCP Client

Configure the client to launch the mcp subcommand:
Start with the MCP health_report tool. Its typed health data and structuredContent.guidance choose the next route from current capability facts. Use raw tools for the full command surface, or use computer_use when the client expects one portable capture/action facade with reusable element handles. When using the MCP collection tool, inspect with the default/list, search, or show action before changing local profiles. The schema is conservatively advertised as destructive and open-world because the same tool can install, update, or publish. Those three write actions enter the audit and optional trajectory; the inspection actions do not. Direct kernel-cli mcp is raw capability just like the direct CLI. Put it behind a harness when mutating tools require human approval.

​
Troubleshooting Order

  1. Run kernel-cli --json doctor.
  2. Confirm the interactive desktop session and display/accessibility bus.
  3. Confirm the permission or helper named by doctor.
  4. Check app/window state and get a fresh target snapshot.
  5. Prefer accessibility or target actions before OCR and coordinates.
  6. Verify the resulting state.
  7. Check whether the harness refused the action by policy.
For Linux dependency setup, run:
For the full platform audit checklist:
See the Reference for command families, permissions, platform boundaries, and operations.