> ## 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 Workflows > Safe, verifiable workflows for installing Kernel CLI, checking live capabilities, observing the desktop, acting on targets, and using the NIIA OTP harness. 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.11`, OpenCLIs build `2026-07-21-154218`.* ## 1. Install and Prove the Binary ```bash theme={null} openclis install kernel-cli command -v kernel-cli kernel-cli --version kernel-cli --json doctor ``` The four outputs prove different things: | Check | What it proves | | ------------------------ | -------------------------------------------- | | `command -v` | Which executable your shell will run | | `--version` | The installed binary version | | OpenCLIs install receipt | Which registry build is installed | | `doctor` | Which capabilities work in this live session | Use `openclis update kernel-cli` to update an existing installation. ## 2. Follow the Live Routing Contract ```bash theme={null} kernel-cli kernel-cli --json doctor kernel-cli docs agent-flow ``` 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.11 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: ```bash theme={null} # Current UI and clipboard-linked context kernel-cli --json snapshot # Windows and structured UI kernel-cli --json windows kernel-cli --json ax-tree --app "TextEdit" # Compact interaction map, ranked for an intent kernel-cli --json targets --app "TextEdit" --intent save --top 20 ``` `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: ```bash theme={null} # Page content belongs to DOM/CDP. kernel-cli websurf browse --extract # Browser chrome can be retried through native AX after an accessible launch. kernel-cli app launch --accessible kernel-cli --json ax-tree --app --web-depth 30 ``` 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 ` 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`: ```bash theme={null} # Descend into the app webview through AX; it is not a CDP browser target. kernel-cli --json ax-tree --app --web-depth 30 kernel-cli --json targets --app ``` 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: ```bash theme={null} kernel-cli --json act '' \ --snapshot '' \ --dry-run ``` 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: ```bash theme={null} kernel-cli --json act '' \ --snapshot '' \ --verb reveal ``` ## 5. Act Once, Then Read Back When the preview is correct: ```bash theme={null} kernel-cli --json act '' --snapshot '' ``` 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: ```bash theme={null} kernel-cli --json report kernel-cli --json security kernel-cli --json process --sort cpu --top 5 kernel-cli --json ports kernel-cli --json services kernel-cli --json session ``` 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: ```bash theme={null} # Chromium page DOM before native AX/OCR fallbacks kernel-cli websurf browse --extract # Rendered text that AX cannot see kernel-cli --json read-text --app "Example App" # Visual proof or pixel-only UI kernel-cli capture --window "Example App" ``` 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: ```bash theme={null} kernel-cli collection search whatsapp kernel-cli collection show whatsapp kernel-cli collection install whatsapp kernel-cli profile describe WhatsApp --json kernel-cli gesture read-chat --app WhatsApp --json ``` 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. ```bash theme={null} kernel-cli gesture orbit --app Blender --by 120,40 --conform kernel-cli profile rebaseline Blender ``` `--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: ```bash theme={null} kernel-cli config show --json kernel-cli gesture message --app WhatsApp \ --param contact="My Notes" --param text="smoke" \ --yield --yield-timeout 30 --restore-focus ``` 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: ```bash theme={null} original_app=$(kernel-cli --json frontmost | jq -r .name) kernel-cli gesture open --app WhatsApp --param contact="My Notes" kernel-cli gesture export-chat --app WhatsApp --restore-to "$original_app" ``` `--restore-to ` 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. Bind Keyboard Steps to Application State Do not encode typing, Tab, and Enter as a timed burst. Prove the state that consumes each step: ```text theme={null} paste draft ──▶ value_equals draft ──▶ Tab ──▶ focus_changed ──▶ Enter │ │ └─ timeout/refusal stops the plan └─ no mutation retry ``` For one action, use verification flags: ```bash theme={null} kernel-cli paste "draft" --expect-app TextEdit --verify kernel-cli key tab --wait-focus-change --expect-role AXTextField ``` For a sequence, run a `kernel.input.plan.v1` document: ```bash theme={null} kernel-cli --json input --file form-plan.json ``` The result distinguishes `POSTED`, `OBSERVED`, and `VERIFIED`. A timeout, refusal, or error returns non-zero and never retries the keyboard mutation. See [Verified Input](/kernel-cli/verified-input) for the plan schema and clipboard/focus lease rules. ## 10. Read the Chat Artifact After Export The app pack produces the archive; the embedded reader analyzes it: ```bash theme={null} kernel-cli gesture export-chat --app WhatsApp --restore-to "$original_app" kernel-cli chat ingest ~/Downloads/"WhatsApp Chat - Team.zip" kernel-cli chat show team kernel-cli chat search team "release date" --json kernel-cli chat timeline team --reply-latency ``` `chat show` discloses timestamp-format detection. A forwarded header that would move chronology backward by more than 24 hours remains inside the forwarding message, preventing phantom participants and reply-latency drift. See [Chat Exports](/kernel-cli/chat) for storage, parser, and audit boundaries. ## 11. Import a Chrome Login Without Blending Session Models Use the bridge only when an explicit cookie snapshot is sufficient: ```bash theme={null} kernel-cli websurf bridge install kernel-cli websurf bridge example.com # add --keep for repeated Sync clicks ``` Prerequisite: Monolex desktop must have staged `~/.niia/bin/monolex-native-host` (`.exe` on Windows). The Kernel CLI 0.26.11 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: ```bash theme={null} kernel-cli websurf postcondition navigation \ --cdp-url http://127.0.0.1:9222 \ --link-text Events --container footer \ --expected-url /events --url-match path \ --target 'main h1' --target-text Events ``` Use `postcondition toast --toast [--toast-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. ## 12. Target One Window or Recover a Menu Explicitly ```bash theme={null} kernel-cli --json windows kernel-cli window --id 0x00c00039 focus kernel-cli menu status --app Safari kernel-cli menu close --app Safari ``` `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. ## 13. 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: ```bash theme={null} # Read the interaction map niia observe targets --app "TextEdit" --json # Inspect and unlock control niia control status niia control unlock --scope full --duration 30m # Preview, then act through the gated surface niia control act '' \ --snapshot '' \ --dry-run \ --json niia control act '' --snapshot '' --json # Revoke the grant when the task is done niia control lock ``` The agent should never self-unlock. The human completes the OTP step; the harness controls the scope and duration. ## 14. Connect an MCP Client Configure the client to launch the `mcp` subcommand: ```json theme={null} { "mcpServers": { "kernel-cli": { "command": "kernel-cli", "args": ["mcp"] } } } ``` 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: ```bash theme={null} kernel-cli docs linux-setup ``` For the full platform audit checklist: ```bash theme={null} kernel-cli docs platform-command-checklist ``` See the [Reference](/kernel-cli/reference) for command families, permissions, platform boundaries, and operations.