> ## Documentation Index
> Fetch the complete documentation index at: https://obversa.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Grok CLI Engine

> @obversa/engine-grok-cli: one engine attempt through a fresh Grok CLI process, with your own Grok login.

`@obversa/engine-grok-cli` runs one engine attempt through the `grok`
command-line tool, in a fresh process. Use it to put an xAI model in a seat.

The plugin runs Grok the way you run it: with your own home folder, your
Grok login and your Grok settings. Grok has no [clean mode](#clean), so it
doesn't run clean by default the way the other command-line engines do. Grok
loads the repository's instruction files under its own rules, such as
whether you trust the project. The plugin adds only what the step needs,
through Grok's own flags: the tools and permission rules the step declares,
read-only enforcement where the step only reads, subagents only when the
step asks for them, and structured output.

## Install

<CodeGroup>
  ```bash npm theme={null}
  npm install @obversa/engine-grok-cli
  ```

  ```bash pnpm theme={null}
  pnpm add @obversa/engine-grok-cli
  ```
</CodeGroup>

Included in `@obversa/obversa`.

## Requirements

* Grok CLI 1.0.44, the version the plugin is tested with, at an absolute
  path you pass as `executable`.
* Grok signed in with `grok login`, or a login file you pass as `authFile`.

## Identity

You name the provider and model family in the `identity` option, such as
`{ provider: 'xai', modelFamily: 'grok-4' }`, and the plugin records them as
given. Before its first attempt it runs `grok --version` and refuses to run
if the version differs from `version`.

## Quickstart

`grok(model, { executable })` is the seat helper a `workflow()` role takes,
as `claude(model)` is for Claude. `grok('grok-4', { executable: '/usr/local/bin/grok' })`
is a seat on `grok-4` that reads with `read_file`, `grep` and `list_dir`.
The seat serves the provider `xai` and the model family read from the model
name, `grok` here.

`new GrokCliEngine(options)` is the same engine without the seat identity.
Construct it with the executable, its version and the identity it serves,
then run one request:

```ts examples/safe-node-attempt.ts (excerpt) {2-5} theme={null}
  const grok = validateAgentResult(await new GrokCliEngine({
    executable: grokExecutable,
    version: '1.0.44',
    identity: { provider: 'xai', modelFamily: 'grok-4' },
    permissionMode: 'dontAsk',
  }).run(
    request(directory, 'grok-4-example', RESULT_SCHEMA),
    () => {},
    new AbortController().signal,
  ));
```

The example runs against a scripted executable, so it needs no account.
Each attempt is a fresh Grok process with only the tools and permissions
the request declares. Grok returns a native structured result, which the
public validator checks before its parts are used.

## Options

### `environment` and `authFile`

The child gets your own environment. `environment` sets more values on top
of it. Names that start with `GROK_` are refused.

`authFile` signs Grok in with another login file instead of yours. The
plugin copies that file into a temporary Grok home folder for each attempt,
because Grok's sandbox reads no login outside its home folder. Grok then
reads no settings from your own Grok home folder.

### Tools and permission rules

A step names Grok's own tools, such as `read_file` and `search_replace`, and
the permission rules that allow them, such as `Read` and `Edit`. A workflow
role gives the seat's tools as both. A Grok tool named as a rule is read as
the rule for that tool: `read_file` and `list_dir` as `Read`, `grep` as
`Grep`, `search_replace` as `Edit`, `run_terminal_command` as `Bash`,
`web_fetch` as `WebFetch` and `use_tool` as `MCPTool`.

### `clean`

Grok has no clean mode, so `clean: true` throws an error that says why.
Grok's strict sandbox reads no login outside its own home folder, so a run
can't leave your Grok home out and keep your own login.

Its row in the [engines table](/docs/packages/engines#the-engines): runs on your
setup, no clean mode, read-only held on your setup.

### Your MCP servers and write steps

Grok starts your own MCP servers in every run, from its own settings and
from `~/.claude.json`. A step that declares no MCP tool keeps their tools
from the model. A write step runs in Grok's workspace sandbox, which also
lets the model change files outside the repository: in Grok's own home
folder, `~/.grok`, and in temporary folders.

### The rest

| Field | Type | Default | Description |
| - | - | - | - |
| `executable` | `string` | required | Absolute path to the Grok CLI. Also a `GrokSeatOptions` field. |
| `version` | `string` | required | The version the CLI must report. Also a `GrokSeatOptions` field, `1.0.44` by default. |
| `identity` | `{ provider, modelFamily }` | required | What this instance serves; either may be `null`. |
| `tools` | `readonly string[]` | `read_file`, `grep`, `list_dir` | `GrokSeatOptions` only: the tools the seat may use. |
| `permissionMode` | `PermissionMode` | none | The CLI's permission mode. |
| `effort` | `string` | none | Passed as `--reasoning-effort <level>`. A request's `effort` wins. Also a `GrokSeatOptions` field. See [Reasoning effort](/docs/packages/engines#reasoning-effort). |
| `clean` | `boolean` | [See the default](/docs/packages/engines#the-default) | `true` throws: Grok has no clean mode. [`clean`](#clean). |

## Errors

* **A version that differs from `version`** refuses the run before the first
  attempt.
* **A relative, empty or malformed `executable`** is refused.
* **`EngineError`** kinds as the [API](/docs/packages/api#errors) lists them.

## API

* **`grok(model, options)`**: a `TeamSeat` for a workflow role.
  [Quickstart](#quickstart).
* **`GrokCliEngine`**: the engine class. **`GrokCliEngineOptions`**,
  **`GrokCliIdentity`**, **`GrokSeat`**, **`GrokSeatOptions`**: its types.
* **`buildGrokArgs`**: the argument builder, exported for tests.

## Next steps

* [Safe node attempts](/docs/recording/node-attempts): the whole example, with
  the OpenCode engine beside it and the output.
* [API](/docs/packages/api): the engine contract this plugin implements.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.