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

# Utilities

> The CLI's own housekeeping: version, help and shell autocompletion.

Flags and arguments below are the contract as the binary states it. The global flags (`--json`, `--timeout`, …) apply here too and are documented on [Global flags](/docs/cli/contract/global-flags). Error codes are a workspace-global contract, not a per-command one — the taxonomy, and how to read a code that is not in it, is on [The error envelope](/docs/cli/contract/error-envelope).

## `octolens autocomplete`

Install shell completions (zsh, bash, fish, powershell)

**Arguments**

| Argument | Type   | Required | Description                                             |
| -------- | ------ | -------- | ------------------------------------------------------- |
| `SHELL`  | `enum` | optional | Shell to set up (defaults to the shell you are running) |

**Flags**

| Flag                     | Type      | Required (headless) | Description                                            |
| ------------------------ | --------- | ------------------- | ------------------------------------------------------ |
| `--refresh-cache` (`-r`) | `boolean` | no                  | Rebuild the completion cache and print no instructions |

**Examples**

```bash theme={null}
octolens autocomplete
octolens autocomplete zsh
octolens autocomplete bash
octolens autocomplete powershell
octolens autocomplete fish > ~/.config/fish/completions/octolens.fish
octolens autocomplete --refresh-cache
```

**Returns**

With `--json`, stdout carries one JSON document with these fields.

| Field            | Type                              | Description                                                                                      |
| ---------------- | --------------------------------- | ------------------------------------------------------------------------------------------------ |
| `shell`          | enum: `zsh`, `bash`, `powershell` | The shell the instructions target (detected or named).                                           |
| `instructions`   | string \| null                    | The setup steps as text. `null` under `--refresh-cache`, which prints nothing for humans either. |
| `cacheRefreshed` | boolean                           | Whether this invocation rebuilt the completion cache.                                            |

`autocomplete fish` (and `autocomplete` when fish is detected) never emits this document: it delegates to the raw completion script — see `autocomplete fish`.

Without `--json`: A terminal prints the shell-specific setup instructions.

Example output:

```json theme={null}
{
  "shell": "zsh",
  "instructions": "1) Add the completion script to your .zshrc …",
  "cacheRefreshed": true
}
```

**Exit codes** — `0` OK · `1` UNEXPECTED · `2` USAGE. The full map is on [Exit codes](/docs/cli/contract/exit-codes).

## `octolens autocomplete fish`

Print fish shell completions (zsh, bash, powershell: `autocomplete <shell>`)

**Examples**

```bash theme={null}
octolens autocomplete fish > ~/.config/fish/completions/octolens.fish
```

**Returns**

stdout is the fish completion SCRIPT itself, in every mode (`--json` included) — the documented install recipe `octolens autocomplete fish > ~/.config/fish/completions/octolens.fish` must write a valid script file, so the output is never wrapped in JSON.

**Exit codes** — `0` OK · `1` UNEXPECTED · `2` USAGE. The full map is on [Exit codes](/docs/cli/contract/exit-codes).

## `octolens help`

Show help for the CLI, a command group, or a single command

**Arguments**

| Argument  | Type     | Required | Description                                         |
| --------- | -------- | -------- | --------------------------------------------------- |
| `COMMAND` | `string` | optional | Command or group to describe (e.g. `mentions list`) |

**Examples**

```bash theme={null}
octolens help
octolens help mentions
octolens help mentions list
```

**Returns**

renders the same prose help pages `--help` does (for the root, a group, or a single command); there is no machine-readable form, and `--json` is REFUSED with the `JSON_NOT_SUPPORTED` error envelope (exit 2) rather than putting prose on a stdout the agent contract promises is JSON. For commands-as-data, read the shipped `COMMANDS.md`.

**Exit codes** — `0` OK · `1` UNEXPECTED · `2` USAGE. The full map is on [Exit codes](/docs/cli/contract/exit-codes).

## `octolens version`

Show the Octolens CLI version, edition, and build metadata

**Examples**

```bash theme={null}
octolens version
octolens version --json
```

**Returns**

With `--json`, stdout carries one JSON document with these fields.

| Field     | Type                         | Description                                                                                |
| --------- | ---------------------------- | ------------------------------------------------------------------------------------------ |
| `version` | string                       | The CLI package version.                                                                   |
| `edition` | enum: `internal`, `customer` | Build edition: published npm package or in-repo source.                                    |
| `channel` | enum: `npm`, `source`        | Distribution channel the binary was built for.                                             |
| `commit`  | string \| null               | Short git commit — baked into npm builds, resolved live from the worktree for source runs. |
| `builtAt` | string \| null               | ISO build timestamp. `null` for live source runs.                                          |
| `node`    | string                       | The Node.js version executing the CLI.                                                     |

Without `--json`: A terminal prints one `octolens/<version> (…)` line.

Example output:

```json theme={null}
{
  "version": "0.9.2",
  "edition": "customer",
  "channel": "npm",
  "commit": "c5a60f7",
  "builtAt": "2026-08-01T12:00:00.000Z",
  "node": "v22.17.0"
}
```

**Exit codes** — `0` OK · `1` UNEXPECTED · `2` USAGE. The full map is on [Exit codes](/docs/cli/contract/exit-codes).