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

# CLI Commands

> Full reference for all cogniscape commands and flags.

## Onboarding commands

### `cogniscape init`

Save your customer key to the machine-level config.

```bash theme={null}
cogniscape init <customer-key>
```

<ParamField path="customer-key" type="string" required>
  Your Cogniscape customer key. Find it in the Cogniscape dashboard under Settings → API Keys.
</ParamField>

**What it does:**

<Steps>
  <Step title="Creates ~/.cogniscape/config.json">
    Saves the customer key at the machine level — shared across all projects on this machine.
  </Step>

  <Step title="Installs Claude Code hooks">
    Merges Cogniscape hooks into `~/.claude/settings.json` automatically.
  </Step>

  <Step title="Installs Cursor hooks (if detected)">
    If `~/.cursor/` exists, merges hooks into `~/.cursor/hooks.json` automatically.
  </Step>
</Steps>

Running `cogniscape init` again overwrites the existing key (idempotent).

<Note>
  The install script runs `cogniscape init` automatically when you pass your customer key. You only need to run this manually if you installed the binary without a key or want to change keys.
</Note>

***

### `cogniscape update-key`

Update the customer key for the current project.

```bash theme={null}
cogniscape update-key <new-customer-key>
```

Fails with an error if the machine has not been initialized with `cogniscape init` first.

***

### `cogniscape setup-hooks`

Install Claude Code hooks manually.

```bash theme={null}
cogniscape setup-hooks
```

Merges Cogniscape hooks into `~/.claude/settings.json`, preserving any existing third-party hooks. Creates a backup at `~/.claude/settings.cogniscape-backup.json` before modifying. Idempotent — will not duplicate hooks already present.

<Note>
  `cogniscape init` runs this automatically. Use `cogniscape setup-hooks` directly only if you need to repair or re-install hooks without changing your customer key.
</Note>

**Claude Code hooks installed:**

| Event          | Matcher        | What it captures              |
| -------------- | -------------- | ----------------------------- |
| `SessionStart` | —              | Session lifecycle begin       |
| `Stop`         | —              | Session summary + token usage |
| `PostToolUse`  | `ExitPlanMode` | Plan approval                 |
| `PostToolUse`  | `TaskCreate`   | Task creation                 |
| `PostToolUse`  | `TaskUpdate`   | Task completion               |

**Cursor hooks installed** (in `~/.cursor/hooks.json`, auto-detected when `~/.cursor/` exists):

| Event          | What it captures                            |
| -------------- | ------------------------------------------- |
| `sessionStart` | Session lifecycle begin                     |
| `stop`         | Session summary (full conversation content) |
| `sessionEnd`   | Session lifecycle end                       |

***

### `cogniscape mcp update`

Scan your machine for all AI tools with Cogniscape MCP configurations and update them to the latest format.

```bash theme={null}
cogniscape mcp update
```

Detects and updates configurations in Claude Code, Cursor, Codex, and OpenCode. Migrates legacy URLs and incompatible formats automatically.

| Flag              | Description                                           |
| ----------------- | ----------------------------------------------------- |
| `--dry-run`       | Preview what would change without modifying any files |
| `--verbose`       | Show file paths of modified configs                   |
| `--only "<tool>"` | Update only a specific tool (e.g., `--only "Cursor"`) |

<Note>
  Claude Desktop is configured through the claude.ai web account ([Add custom connector](https://claude.ai/settings/connectors?modal=add-custom-connector),
  Streamable HTTP) and inherited by the Desktop and mobile apps.
  The CLI does not manage Claude Desktop config.
</Note>

***

### `cogniscape uninstall`

Remove hooks and the binary.

```bash theme={null}
cogniscape uninstall
```

Removes Cogniscape hooks from `~/.claude/settings.json` and `~/.cursor/hooks.json`, then deletes the binary. Idempotent. On Windows, the binary cannot be self-deleted while running — a message will indicate the path for manual removal.

***

## `cogniscape version`

```bash theme={null}
cogniscape version
# cogniscape (go) v1.7.1
```

***

## Authentication

All commands that call the API require a customer key, resolved in this order:

1. `--customer-key` flag
2. `COGNISCAPE_CUSTOMER_KEY` environment variable
3. `~/.cogniscape/config.json` (machine-level, set by `cogniscape init`)
4. Error if none of the above is set

The key is sent as the `X-Cogniscape-Customer-Key` HTTP header on all requests.

***

## Local files

| Path                                     | Purpose                                                                                  |
| ---------------------------------------- | ---------------------------------------------------------------------------------------- |
| `~/.cogniscape/config.json`              | Machine-level customer key. Created by `cogniscape init`. Shared across all projects.    |
| `~/.cogniscape/hooks.log`                | Hook execution log. Rotated to the last 1000 lines when it exceeds 80 KB.                |
| `~/.cogniscape/hooks-debug.jsonl`        | Raw hook payloads in JSONL format (debug). Same rotation policy.                         |
| `~/.cogniscape/task-cache/<id>.json`     | Ephemeral task metadata for create→complete correlation. Purged on session end.          |
| `~/.claude/settings.json`                | Global Claude Code settings. `cogniscape setup-hooks` adds hooks here.                   |
| `~/.cursor/hooks.json`                   | Cursor hooks config. Created automatically by `cogniscape init` when Cursor is detected. |
| `~/.cursor/hooks.cogniscape-backup.json` | Backup of Cursor hooks before modification.                                              |