> ## 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 in connector.json

> How connector.json composes Kernel CLI observation and control while NIIA owns the human authorization boundary.

Kernel CLI is the raw operating-system capability surface used by
`connector.json` workflows. It can provide structured observation, semantic UI
actions, machine telemetry, pixel fallbacks, and typed MCP tools without making
the connector format itself an OS driver.

<Card title="Read the canonical Kernel CLI docs" icon="microchip" href="/kernel-cli">
  The canonical overview, installation path, cross-platform contract, and safety
  boundaries now live at `/kernel-cli`.
</Card>

## The Boundary

Each layer owns a different contract:

| Layer            | Responsibility                                            |
| ---------------- | --------------------------------------------------------- |
| Kernel CLI       | Observe and control the local operating system            |
| `connector.json` | Compose commands into a repeatable workflow               |
| NIIA             | Apply human authorization and time-limited control policy |

Kernel CLI remains a standalone binary. A connector can call its raw commands,
carry structured values between phases, and require a harness for writes.

```text theme={null}
connector phase
      ↓
Kernel CLI observation
      ↓
target_id + snapshot_id
      ↓
dry-run / policy decision
      ↓
Kernel CLI action
      ↓
read-back verification
```

## Recommended Connector Flow

1. Run `doctor` or an equivalent health check on the target machine.
2. Observe with `snapshot`, `windows`, `ax-tree`, or `targets`.
3. Preserve `snapshot_id` and `target_id` between phases.
4. Resolve the action with `act --dry-run`.
5. Require the configured harness before a mutating phase.
6. Act once and verify through a fresh read.

This flow is capability-first. OCR, screenshots, and coordinates remain
available when the target has no useful semantic surface.

## Connector Handles and MCP Element Tokens

`connector.json` can carry Kernel CLI result fields between steps, including
target and geometry guards. It does **not** mint MCP `element_token` values.

Reusable `element_token` values belong to the MCP `computer_use` facade. Use
that facade when a client expects one portable capture/action loop; use raw
Kernel CLI commands when the workflow needs the full OS surface.

## Raw and Harnessed Execution

Direct Kernel CLI commands execute without an NIIA approval gate. For
human-gated control, route the write through the NIIA control surface:

```bash theme={null}
niia observe targets --app "TextEdit" --json
niia control unlock --scope full --duration 30m
niia control act '<target_id>' --snapshot '<snapshot_id>' --dry-run --json
```

The human completes the OTP step. The connector does not grant itself control.

## Continue Reading

<CardGroup cols={2}>
  <Card title="Kernel CLI Overview" icon="microchip" href="/kernel-cli">
    Product identity, capability surfaces, cross-platform behavior, and the raw
    versus harnessed boundary.
  </Card>

  <Card title="Kernel CLI Workflows" icon="route" href="/kernel-cli/workflows">
    The observe, dry-run, act, verify, and NIIA-gated flows.
  </Card>

  <Card title="Kernel CLI Reference" icon="book" href="/kernel-cli/reference">
    Commands, permissions, platform behavior, operations, audit, and MCP.
  </Card>

  <Card title="connector.json" icon="diagram-project" href="/openclis/specs/connector-json/index">
    Return to the connector specification and orchestration model.
  </Card>
</CardGroup>