> ## 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.
# Complete Command Reference
> All 111 Kernel CLI commands, including purpose, important controls, verification behavior, and runtime boundaries.
This is the complete public index for the Kernel CLI command surface. It covers
all 111 commands shown by `kernel-cli --help`: 110 product commands plus the
generated `help` command.
*Verified against `kernel 0.26.11`, OpenCLIs build
`2026-07-21-154218`.*
Every command exists in the macOS, Linux, and Windows CLI builds. A command can
still report an unavailable or reduced capability when the current OS, desktop
session, permission set, or helper cannot provide its backend. Run
`kernel-cli --json doctor` for live capability truth.
## How to Read This Reference
```text theme={null}
observe state
↓
resolve a semantic target
↓
preview or check readiness
↓
act once
↓
read back and verify
```
The tables describe the public behavior and the controls most important for
choosing a command. The installed binary remains the exact syntax authority:
```bash theme={null}
kernel-cli --help
kernel-cli --help
kernel-cli docs
```
The global help is the complete command inventory, command help is the exact
syntax contract, and `docs` serves the conceptual and platform guides embedded
in that installed release.
Version 0.26.11 provides static sibling-aware epilogues on 32 related commands.
They identify stronger or adjacent commands in the same observation, semantic
write, visual, pointer, keyboard, window, or browser-state family. These
epilogues improve discovery; dynamic result routing still comes only from the
guidance object emitted for the current invocation.
Direct Kernel CLI use has no NIIA approval gate. Mutating commands execute
immediately and are written to the local audit log by default. Use the NIIA
harness when a human must authorize writes before they run.
## Global Controls
| Control | Meaning |
| ---------------------- | ------------------------------------------------------------------------------------------------ |
| `--json` | Request structured output when the command supports it. Use this for agents and automation. |
| `--no-audit` | Suppress the normal local audit record for a mutating command. It does not change authorization. |
| `--help` | Print exact arguments and options for the selected command. |
| `--version` | Print the installed Kernel CLI version. |
| `--status` | On commands that expose it, check backend readiness without performing the normal read or write. |
| `--dry-run` or `--dry` | On commands that expose it, resolve the intended action without applying it. |
## Result Guidance and Output Streams
Introduced in version 0.24.8 and retained in 0.26.11, one result-specific
`[NEXT]` recommendation can be appended for commands where the current
invocation establishes a useful route:
| Mode | Primary result | Guidance |
| ----------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| Human CLI | Normal stdout | Human `[NEXT]` block on stderr; binding rows add `[IAW-SOP]`, and `ORDER` rows are numbered |
| CLI with `--json` | Unchanged JSON stdout | One compact `[NEXT] {json}` line on stderr with stable `id` and `sop` |
| Native MCP | Normal `content` and any typed `structuredContent` | The same versioned object at `structuredContent.guidance` |
The schema-v2 guidance object contains `v`, stable `id`, `phase`, `sop`,
`reason`, `next`, `avoid`, `docs`, and `confidence`. `sop` is `order`, `route`,
or `advisory`. It is emitted at most once per process, does not change the
command exit code, and never claims knowledge from an earlier invocation.
Existing MCP error objects keep `error`, `class`, and `try_next`; mapped errors
add `guidance` rather than replacing those fields. The current 0.26.11 runtime classifies
errors centrally so commands without a local emitter still receive a known
permission, stale/offscreen/not-found/ambiguity, or app/focus recovery route.
## Desktop and Interface Observation
These commands describe visible applications, windows, accessibility state,
rendered pixels, and the targets an agent can act on.
| Command | What it does | Important controls |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `snapshot` | Collects a combined desktop snapshot containing windows, accessibility state, and clipboard-linked context. | `--raw`, `--status` |
| `windows` | Lists visible windows with identifiers, owning applications, titles, and geometry. | Use `--json` when another command will consume a window id. |
| `ax-tree` | Reads the accessibility tree for the focused or selected application. An empty Chromium-scoped result emits `targets.browser_shallow`. In 0.24.11, an explicit non-browser `--app` whose non-empty tree contains web content emits `ax_tree.webview_content` when `--web-depth` was not already supplied. | `--app`, `--pid`, `--depth`, `--web-depth`, `--raw` |
| `read` | Reads the value and selection of the focused field, a named element, or a selected window. | `--app`, `--window`, `--element` |
| `elements` | Lists accessible buttons, fields, checkboxes, and other actionable elements. An empty Chromium-scoped result emits `targets.browser_shallow` in 0.24.10. | `--app` |
| `url` | Reads the active browser tab URL when the browser exposes it through scripting or accessibility. A confirmed browser with no exposed URL emits `url.native_unreadable`, which recommends explicit address-bar copy or `websurf` instead of OCR bytes. | `--app`, `--status` |
| `displays` | Lists displays, bounds, resolutions, and the main-display designation for coordinate work. | Use the returned display index with capture, OCR, tiling, and display control. |
| `frontmost` | Identifies the application currently receiving user interaction. | Bundle identifiers are platform-specific; the app name and process id are the portable fields. |
| `apps` | Lists running GUI applications, distinct from the complete process list. | Use `process` for background and non-GUI processes. |
| `capture` | Captures a display, region, or window as an image, and can record a bounded animated GIF. | `--display`, `--region`, `--window`, `--peek`, `--gif`, `--duration-ms`, `--fps`, `--output`, `--status` |
| `read-text` | Runs OCR over a display, region, application window, or exact window so rendered text can be read when accessibility cannot expose it. | `--find`, `--lang`, `--display`, `--region`, `--app`, `--window` |
| `read-barcodes` | Detects QR codes and supported barcode formats in rendered pixels. | `--region`, `--status`; non-QR formats depend on platform capability. |
| `targets` | Builds one ranked interaction map from accessible controls and rendered-text targets. `observe` is an alias. Version 0.24.9 keeps AX-only results when optional OCR is unavailable and routes mixed results as `targets.actionable` whenever any AX handle exists. In 0.24.10, an empty Chromium-scoped result emits `targets.browser_shallow`; non-browser empty results keep `targets.empty`. Version 0.25.0 auto-bounds OCR to the requested app's visible window and omits OCR, with an explicit reason, when that app is occluded. The command still fails when neither backend produced evidence. | `--app`, `--region`, `--top`, `--intent`; inspect `ocr_included`, `ocr_region`, and `ocr_omitted_reason`, then pass `target_id` and `snapshot_id` to `act`. |
## Web-Page Automation
Kernel CLI embeds the reusable `lib-monosurf` facade over
`lib-monosurf-core` for structured page work. Use this before AX, OCR, or
coordinate input when the target is inside a Chromium page.
| Command | What it does | Important controls |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `websurf` | Runs the complete shared MonoSurf 0.11.3 surface in-process. It owns DOM/JS/CDP, persistent profiles, explicit cookie-only bridge import, exact navigation/toast postconditions, external Electron/WebView2/Tauri/Chromium attach, site plugins, collection, network evidence, screenshots, console checks, and browser QA. | Families: `start`, `stop`, `profiles`, `profile`, `browsers`, `login`, `browse`, `postcondition`, `bridge`, `x`, ``, `sites`, `batch`, `auth`, `doctor`, `selftest`, `docs`; bridge actions `install`, `[domain]`, `--keep`; browse controls `--profile`, `--ephemeral`, `--cdp-url`, `--eval`, `--extract`, `--collect`, `--net-log`, `--shot`, `--console`, `--net`, `--wait`, `--expect`. See the [complete shared reference](/monosurf/usage). |
| `chat` | Runs the embedded conversational-export reader over the shared monochat core and store. It ingests WhatsApp text/ZIP exports, then lists, reads, searches, measures, and exports them. | Verbs: `ingest`, `list`, `show`, `read`, `search`, `stats`, `timeline`, `export`; machine output with `--json`; message ranges with `--sender`, `--since`, `--until`, and `--limit`. See [Chat Exports](/kernel-cli/chat). |
The embedded command and standalone [MonoSurf](/monosurf/index) use the same
profile registry, plugins, grants, and state under
`Application Support/Monolex/monosurf/`. They also share the canonical help,
embedded docs, and profile TUI. Kernel CLI calls that facade in-process without
starting a standalone `monosurf` subprocess, and continues to own browser
chrome, native dialogs, permission prompts, and non-browser desktop UI.
## Reactive Observation
Reactive commands wait for a bounded condition or stream bounded events. They
do not need an unbounded polling loop.
| Command | What it does | Important controls |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `logs` | Queries recent system logs or follows a live bounded stream. | `--last`, `--process`, `--predicate`, `--limit`, `--follow`, `--duration-ms` |
| `log` | Reads recent platform log entries for one application or process. | `--minutes`, `--seconds` |
| `monitor` | Streams supported kernel-level events when the platform backend and required privileges are available. | `--list`, event names, `--duration-ms`, `--count`; privileged event sources may require administrator access. |
| `watch` | Watches a file or directory for bounded filesystem changes. | Path argument, `--recursive`, `--duration-ms`, `--count` |
| `ax-watch` | Streams accessibility notifications such as focus, title, value, and window changes. | `--app`, `--events`, `--duration-ms`, `--count` |
| `wait` | Waits for accessible or OCR text to appear or disappear, for an app to become frontmost, or for pixels in a region to change. | `--timeout`, `--frontmost`, `--app`, `--gone`, `--ocr`, `--region`, `--changed`, `--status` |
| `notifications` | Reads recent desktop notifications when the active platform exposes them. | `--limit`, `--status` |
## Machine, Process, and Network State
These commands inspect the computer itself without requiring a separate
telemetry agent. Platform-specific fields are returned only when the operating
system can provide them.
| Command | What it does | Important controls |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `hardware` | Reports machine identity and core specifications such as model, processor, memory, and core count. | Serial and platform identifiers depend on OS visibility. |
| `devices` | Inventories connected storage, USB, graphics, displays, audio, cameras, and other exposed devices. | Device categories vary by platform. |
| `stats` | Reports live load, memory, disk, swap, and available thermal or sensor telemetry. | Sensor depth varies by hardware and OS. |
| `power` | Samples available power and energy telemetry. | `--interval-ms`, `--detailed`; wattage and residency fields appear only when exposed. |
| `assertions` | Shows inhibitors that keep the machine awake or delay sleep and shutdown. | Read-only; the underlying inhibitor model is platform-specific. |
| `ports` | Lists listening TCP ports or established connections with process ownership when available. | `--established` |
| `cpu` | Samples current total CPU usage and optional per-core activity. | `--interval-ms`, `--per-core` |
| `security` | Summarizes the host security posture, including the platform's boot, encryption, firewall, malware-protection, and update signals. | Returned checks differ across macOS, Linux, and Windows. |
| `idle` | Reports time since the last user input. | Desktop-session visibility is required. |
| `wifi` | Reads Wi-Fi link details, joins a network, or turns the radio on and off. | Actions: read status, `join `, `on`, `off`; use `--password-stdin` for secrets. |
| `kexts` | Lists loaded kernel extensions, modules, system extensions, or drivers. | The name reflects the macOS origin; Linux and Windows return their equivalent driver surface. |
| `now-playing` | Reads the active system media session and currently playing item. | Availability depends on the desktop media-session API. |
| `session` | Reports current user-session state such as idle time, cursor position, lock state, appearance, and keyboard layout when exposed. | Fields are capability-dependent. |
| `proxy` | Reads HTTP, HTTPS, SOCKS, and automatic proxy configuration. | Sources include system settings and relevant desktop or environment configuration. |
| `backup` | Reports available backup posture signals such as configured services, timers, history, or restore protection. | The backup model differs by platform. |
| `netusage` | Shows per-process network use and top consumers when the OS exposes accounting data. | Process attribution can be reduced without elevated visibility. |
| `services` | Lists loaded or registered background services and their current process or failure state. | Maps to the native service manager on each platform. |
| `schedule` | Lists deferred work such as timers, scheduled tasks, cron entries, and launch jobs. | `--system`, `--all`; output declares sources it could not observe. |
| `route` | Reports the default network route, primary interface, and gateway. | Read-only. |
| `powercfg` | Reads sleep, hibernation, low-power, and active power-profile settings. | Read-only; fields map to each platform's power model. |
| `installed` | Lists installed applications and packages visible through native application or package registries. | Sources vary by platform and installation method. |
| `report` | Produces a one-shot aggregate of machine, security, session, network, service, and top-process state. | Use `--json` for a portable diagnostic bundle. |
| `process` | Lists, filters, ranks, kills, suspends, resumes, or changes the priority of processes. | `--sort`, `--top`, `--kill`, `--force`, `--suspend`, `--resume`, `--renice`, `--priority` |
| `network` | Reads network summary, Wi-Fi, DNS, service, or interface information. | Select `info`, `wifi`, `dns`, `services`, or `interfaces`. |
| `lsof` | Lists open files for a process or the process and socket using a port. | Target a name, pid, or `:`; `--net` selects native socket detail. |
| `fonts` | Lists installed font families, optionally filtered by name. | Filter argument, `--status` |
## Semantic UI Control
Semantic controls act on named elements or stable handles. Prefer them over
coordinates because they preserve intent and can verify the resolved target.
| Command | What it does | Important controls |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `menu` | Lists or invokes an application menu and, on macOS, diagnoses or closes AX-opened menu residue. Normal invocation attempts residue cleanup and reports a cleanup failure. | Path such as `File>Export`; actions `list`, `status`, `close`; `--app`, `--find`, `--dry` |
| `ax-press` | Presses an accessible button by exact title without coordinates; `--prefix` matches the stable head of a state-bearing title such as `Muted, until 8:31 PM`. | `--app`, `--prefix`, `--nth`, `--expect-app`, `--yield`, `--yield-timeout` |
| `ax-set` | Writes a value to a named accessible element. | Title and value arguments, `--app`, `--expect-app`, `--yield` |
| `ax-select` | Sets a text selection range or supported boolean accessibility attribute. | `--ident`, `--range`, `--selected`, `--attr`, `--app`; typed writes are platform-capability dependent. |
| `act` | Resolves a target handle, selects its preferred write path, performs the requested action, and verifies the result where possible. | `--verb auto\|press\|set\|click\|reveal\|action`, `--value`, `--app`, `--snapshot`, `--dry-run`, `--reveal`, `--expect-app`, `--expect-window`, `--expect-focus`, `--strict`, `--yield`, `--yield-timeout`, `--yield-message` |
## Pointer and Keyboard Input
Use pointer and keyboard commands after semantic controls cannot express the
target. Readiness checks and context guards help reduce blind input.
| Command | What it does | Important controls |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `scroll` | Scrolls in a direction, at a position, or until OCR finds target text. | Direction, `--amount`, `--at`, `--modifiers`, `--to`, `--max`, `--pid`, `--real`, `--status` |
| `hid` | Reports whether the optional real virtual-HID input path is available. | Action: `status` |
| `drag` | Drags between absolute points or by a relative delta with optional modifiers and button selection. | `--by`, `--button`, `--modifiers`, `--steps`, `--step-delay-ms`, `--pid`, `--status` |
| `mouse` | Sends one mouse-button down or up event for held-gesture construction. | Actions: `down`, `up`; `--button`, `--modifiers`, `--status` |
| `magnify` | Sends a best-effort trackpad magnification gesture. | Amount from zoom-out to zoom-in; macOS specialized. |
| `rotate` | Sends a best-effort trackpad rotation gesture. | Degrees; macOS specialized. |
| `swipe` | Sends a best-effort multi-finger swipe gesture. | Direction: `up`, `down`, `left`, `right`; macOS specialized. |
| `move` | Moves the pointer to screen coordinates. | X and Y, `--status` |
| `click` | Clicks coordinates supplied either as positional ` ` or the named compatibility pair `--x --y `; partial or mixed forms fail. Supports button/count/modifiers/hold, context guards, and platform-specific background delivery. A verified Chromium `--expect-app` pin or browser-scoped `--skylight --app` resolve emits `coordinate.into_browser`; an unverified coordinate keeps `coordinate.unanchored`. | `--x`, `--y`, `--button`, `--count`, `--modifiers`, `--hold-ms`, `--pid`, `--cursor`, `--skylight`, `--window`, `--app`, `--expect-app`, `--expect-window`, `--status` |
| `click-text` | Finds rendered text with OCR and clicks the selected match. | Query, `--region`, `--nth`, `--dry-run`, `--lang`, `--offset`, `--wait`, `--app`, `--window`, `--status` |
| `right-click` | Sends a right-click at screen coordinates. | X and Y, `--status` |
| `double-click` | Sends a double-click at screen coordinates. | X and Y, `--status` |
| `input` | Executes a strict `kernel.input.plan.v1` sequence and requires each step's observable postcondition before continuing. | `--file `, `--json`, `--no-audit`; see [Verified Input](/kernel-cli/verified-input). |
| `type` | Types text or UTF-8 file contents, optionally proving the resulting value or stable focus state. | Text or `--file`, `--app`, `--delay-ms`, `--pid`, `--real`, `--restore-focus`, `--expect-app`, `--verify`, `--expect-value`, timing controls, `--yield`, `--status` |
| `key` | Sends a key combination and can require focus change, focus identity, or a resulting value. | Combo, `--app`, `--delay-ms`, `--pid`, `--real`, `--restore-focus`, `--expect-app`, focus/value postconditions, timing controls, `--yield`, `--status` |
| `paste` | Uses an exactly-once clipboard lease and can require stable value readback before restoring the prior clipboard. | Text, `--app`, `--menu`, `--verify`, `--expect-value`, timing controls, `--delay-ms`, `--status` |
## Applications, Windows, and System Writes
These commands change application, desktop, device, and user-session state.
Their exact backend and supported action set are reported by `doctor` and each
command's `--status` surface where available.
| Command | What it does | Important controls |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clipboard` | Reads or writes clipboard text and PNG image data. Linux writes return after a clipboard backend becomes the resident selection owner instead of waiting for that owner process to exit. | Actions: `status`, `get`, `set`, `get-image`, `set-image` |
| `window` | Closes, minimizes, maximizes, moves, resizes, focuses, floats, or tiles one window. Linux launch/focus paths settle against the accessible desktop object before reporting success. | Actions: `status`, `close`, `minimize`, `maximize`, `move`, `resize`, `focus`, `float`, `unfloat`; tiles: `left`, `right`, `top`, `bottom`, `top-left`, `top-right`, `bottom-left`, `bottom-right`, `center`, `fill`; exact `--id ` conflicts with `--title`; `--pos`, `--display` |
| `app` | Launches, quits, switches, hides, or lists applications, reports app-control readiness, and inspects renderer accessibility depth. | Actions: `launch`, `quit`, `switch`, `hide`, `list`, `status`, `accessibility`; `--no-wait`, `--timeout-ms`, Linux launch `--accessible` |
| `open` | Opens a URL, custom URL scheme, or path with the operating system. | URL/path or `status` |
| `defaults` | Reads or writes application preferences. | Actions: `status`, `read`, `write`; bundle id, `--key`, `--value`, `--value-type` |
| `shortcut` | Lists or runs operating-system shortcuts and automations. | Shortcut name, `list`, or `status`; optional `--input` |
| `notify` | Sends a desktop notification or opens a bounded reply prompt and returns the user's answer. | Title/message, `status`, `--reply`, `--timeout` |
| `desktops` | Lists virtual desktops, switches desktops, or moves a window between them where supported. | Actions: `list`, `switch`, `move-window`; index, `--window`, `--status`; Linux has the broadest current control surface. |
| `tray` | Lists menu-bar or system-tray items and clicks a named item when the desktop exposes it. | Actions: `list`, `click`; item name, `--status` |
| `say` | Speaks text through the platform text-to-speech service. | Text, `--voice`, `--rate`, `--status` |
| `focus` | Turns Focus or Do Not Disturb on or off where an automation backend is available. | Actions: `on`, `off`; `--name`, `--status`; Windows currently reports unsupported. |
| `display` | Lists display modes, changes resolution, mirrors or unmirrors displays, and controls Night Shift where available. | Actions: `modes`, `set`, `mirror`, `unmirror`, `night-shift`; `--display`, `--status` |
| `bluetooth` | Reads adapter state, toggles the adapter, lists devices, or connects and disconnects a device. | Actions: `status`, `on`, `off`, `list`, `connect`, `disconnect`; MAC address, `--status` |
| `brightness` | Reads, sets, raises, or lowers display brightness. | Actions: `get`, `up`, `down`, `set`; level or step, `--status` |
| `input-source` | Reads, lists, or selects the keyboard input source or IME. | Actions: `get`, `list`, `set`; name, `--status` |
| `audio` | Lists audio devices or selects the default input or output device. | Actions: `list`, `set`; device name, `--input`, `--status` |
| `media` | Controls the active media session. | Actions: `play-pause`, `play`, `pause`, `stop`, `next`, `prev`; `--status` |
| `volume` | Reads, sets, adjusts, or mutes output volume. | Actions: `get`, `up`, `down`, `set`, `mute`; value or mute state, `--status` |
| `awake` | Starts, stops, or inspects a keep-awake inhibitor. | Actions: `on`, `off`, `status`; optional `--duration` |
| `lock` | Locks the current user session. | `--status` checks readiness without locking. |
## Data, Files, and Evidence
These commands read structured application data, find files, inspect
provenance, and compare saved observations.
| Command | What it does | Important controls |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `query` | Queries supported application databases such as browser history, notes, photos, messages, and shell history. | Target or `list`, optional `--sql`, `--raw`; protected stores can require additional permission. |
| `search` | Searches file names, paths, and indexed metadata through the platform's available search backend. | Query, `--limit`, `--in`, `--name`, `--kind`, `--modified-since` |
| `file` | Returns structured metadata for one file or directory, including timestamps, ownership, attributes, links, and available origin markers. | Path, optional `--hash` for SHA-256 |
| `verify` | Verifies a file's hash, signature, trust, notarization, quarantine, or origin evidence available on the platform. | Path, `--deep` for nested macOS code verification |
| `diff` | Compares two saved structured JSON observations and reports added, removed, and changed items. | Before and after files, optional `--key` identity field |
### Supported Query Sources
Run `kernel-cli query list` to ask the installed binary for its current source
list. Version 0.24.11 exposes these public source ids:
| Family | Query source ids |
| ----------------- | --------------------------------------------------------------------------------------------- |
| Browser history | `safari`, `chrome`, `brave`, `edge`, `arc`, `vivaldi` |
| Browser downloads | `chrome-downloads`, `brave-downloads`, `edge-downloads`, `arc-downloads`, `vivaldi-downloads` |
| Browser bookmarks | `safari-bookmarks`, `chrome-bookmarks`, `brave-bookmarks`, `edge-bookmarks` |
| Personal data | `notes`, `photos`, `messages`, `contacts`, `mail`, `calendar`, `reminders` |
| System evidence | `quarantine`, `knowledgec` |
| Shell history | `shell-history`, `zsh-history`, `bash-history` |
Protected application stores can require additional permission. An unavailable
store returns a capability or permission error rather than silently changing to
another source.
## Automation, Safety, and Integration
These commands explain, configure, audit, compose, record, and expose the
capability surface.
| Command | What it does | Important controls |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `script` | Runs a platform-native automation script: AppleScript or JXA on macOS, PowerShell on Windows, and a POSIX shell on Linux. | Script text, `--jxa`, `--status`; this is a high-power write surface. |
| `docs` | Lists or prints conceptual documentation embedded in the installed binary. It is not a substitute for per-command help. | Run without a topic to list canonical ids; `agent-flow` is the route-selection guide. Use `kernel-cli --help` for exact syntax. |
| `audit` | Reads the local mutating-command audit log or prints its path. | `--limit`, `--path` |
| `undo` | Restores the previous state for recent actions that recorded a readable, repeatable inverse. | `--last`, `--list`; one-way actions and arbitrary input are not automatically reversible. |
| `trace` | Runs a command and builds a bounded causal view of spawned processes, file writes, and network activity that the active platform can observe. | Command string, `--window-ms`; deeper file attribution can require elevated access. |
| `chrome-clones` | Lists or removes stale Chromium automation clones left in temporary storage. | `--clean`, `--all`; macOS specialized. |
| `refiner` | Initializes, lists, or tests output-refiner plugins. | Action: `init`, `list`, or plugin name. |
| `gesture` | Runs a named, parameterized gesture from an application profile, checks frame-sensitive geometry, honors the gesture/machine focus policy, and returns the profile's resolved follow-ups. | Gesture name, required `--app`, optional `--by`, `--amount`, `--dir`, repeated `--param`, `--conform`, `--yield`, `--yield-timeout`, `--restore-focus`; `--restore-to ` explicitly restores a pre-chain app and implies restore |
| `collection` | Discovers, verifies, installs, updates, sideloads, or owner-publishes curated profile packs from the OpenCLIs CDN. `list` and `show` expose `[frame-bound N]` and `[size-scaled N]` sensitivity before install/run. | Actions `list`, `search`, `show`, `install`, `update`, `publish`; target/query, `--from`, `--force`, `--json` |
| `profile` | Lists, installs, locates, describes, scaffolds, records, derives, or rebaselines reusable application action profiles; `describe` exposes pack/gesture notes and follow-up arrays. | Actions include `list`, `install`, `path`, `describe`, `scaffold`, `record`, `from-index`, `rebaseline`; `--write`, `--duration-ms`, `--out`, `--last` |
| `config` | Shows, initializes, or locates Kernel CLI timing and focus-policy configuration. | Actions: `show`, `init`, `path`; the JSON `focus` object owns busy/yield/restore defaults |
| `mcp` | Starts the stdio MCP server and exposes the raw command surface as typed tools. | Configure the client to run `kernel-cli mcp`; use MCP `health_report` before control. |
| `record` | Starts, stops, or inspects recording of mutating MCP tool trajectories with secret redaction. | Actions: `start`, `stop`, `status`; `--out`, `--with-screenshots` |
| `replay` | Replays a recorded trajectory through the current live tool path, re-resolving supported handles. | Trajectory JSONL file from `record` |
| `permissions` | Checks, opens, requests, or explains the permission surface used by Kernel CLI. | Actions: `status`, `grant`, `open`, `request`; direct system requests are primarily macOS. |
| `doctor` | Probes the current machine and session, maps capabilities to requirements, and gives remediation. | `--fix` prints Linux helper installation guidance; add `--yes` only when you intend to run it. |
| `help` | Prints global help or detailed help for one command. | `kernel-cli help` or `kernel-cli help ` |
Version 0.26.1 adds no root command. It makes profile-level `note` (including
the legacy `_note` alias), gesture-level `note`, and gesture-level `next`
first-class output. Human gesture success appends `[NEXT] declared by the
profile:`; JSON returns a parameter-resolved `next` array. On macOS, a busy
focus-yield uses an explicit OK/Cancel dialog plus the idle threshold; other
platforms retain the notification-and-idle fallback.
### MCP Mapping
`kernel-cli mcp` exposes 116 tools in version 0.26.11. It maps all 111 root
commands to normalized MCP names; hyphenated commands use underscores. Five
MCP-native or compatibility tools extend the mapped set:
| MCP-only name | Purpose |
| --------------- | --------------------------------------------------------------------------------------------------------------------- |
| `computer_use` | Capture/action facade with screenshot, structured-element, reusable-handle, and explicit no-focus/no-cursor policies. |
| `health_report` | Machine-readable permission and capability probe. |
| `connections` | Typed process-to-socket connection view. |
| `trackpad` | Compatibility entry point for magnify, rotate, and swipe gestures. |
| `type_text` | Compatibility entry point for typed text input. |
The MCP `websurf` tool provides typed `plan`, `browsers`, `profiles`, and `site`
operations. The full set of web command flags and compatibility routes remains
under `kernel-cli websurf`.
The multi-action MCP `collection` tool is advertised by its strongest action:
`readOnlyHint: false`, `destructiveHint: true`, `idempotentHint: false`, and
`openWorldHint: true`. Its capability list is `tooling.control`,
`network.read`, and `network.write`. At execution time only `install`,
`update`, and `publish` enter the mutating audit and record/replay trajectory;
the default `list` plus `list`, `search`, and `show` do not.
### Embedded Documentation Topics
`kernel-cli docs` lists the topics compiled into the installed executable.
Version 0.26.11 includes the `agent-flow` routing contract, verified input,
embedded chat, app-pack authoring, product and
operations guides, platform guides for
macOS, Linux, and Windows, computer-use guides, recording and test guides,
implementation comparison, Linux setup, the platform command checklist, and
the observe, control, system, MCP, websurf, and permission-safety surfaces.
## Capability and Safety Rules
| Rule | Why it matters |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| Run `doctor` first | The same binary can have different capabilities in a local desktop, remote shell, headless service, or restricted session. |
| Prefer semantic controls | `act`, accessibility actions, menus, and named fields carry stronger intent than coordinates. |
| Use readiness and preview modes | `--status`, `--dry-run`, and strict context guards reduce accidental reads and writes. |
| Verify after acting | Re-read the surface that owns the result before trying another backend. |
| Treat read commands as sensitive | Clipboard, OCR, screenshots, app databases, logs, and accessibility state can expose private data. |
| Put authorization in a harness | The audit log records what happened; NIIA or another harness decides whether a write may happen. |
## Related Guides
Follow the observe, preview, act, and verify loop.
Understand platforms, permissions, audit, MCP, and release proof.
Read and analyze exported human conversations.
Bind keyboard steps to stable application state.