> ## 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](https://octolens.com/docs/cli/contract/global-flags.md). 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](https://octolens.com/docs/cli/contract/error-envelope.md).

## `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](https://octolens.com/docs/cli/contract/exit-codes.md).

## `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](https://octolens.com/docs/cli/contract/exit-codes.md).

## `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](https://octolens.com/docs/cli/contract/exit-codes.md).

## `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](https://octolens.com/docs/cli/contract/exit-codes.md).


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