Skip to main content

​
Onboarding commands

​
cogniscape init

Save your customer key to the machine-level config.
​
string
required
Your Cogniscape customer key. Find it in the Cogniscape dashboard under Settings → API Keys.
What it does:
1

Creates ~/.cogniscape/config.json

Saves the customer key at the machine level — shared across all projects on this machine.
2

Installs hooks for every AI coding agent on the machine

Runs cogniscape setup-hooks: Claude Code, Codex, Cursor, OpenCode, and Kiro. See the hook tables below.
Running cogniscape init again overwrites the existing key (idempotent).
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.

​
cogniscape update-key

Replace the machine-level customer key in ~/.cogniscape/config.json.

​
cogniscape setup-hooks

Install or repair the hooks of every supported AI coding agent.
Merges Cogniscape hooks into each agent’s configuration, preserving any existing third-party hooks. A configuration file that is not valid JSON is left untouched. Idempotent — hooks already present are not duplicated. Agents that are not installed are skipped.
You rarely need this command. cogniscape init runs it, and the CLI rechecks the hooks on its own at most once an hour while any captured agent is in use: a missing hook, or an agent installed after Cogniscape, is fixed automatically.
What each agent provides is listed in the capability matrix. Claude Code hooks (in ~/.claude/settings.json; backup at ~/.claude/settings.cogniscape-backup.json): Codex hooks (in ~/.codex/hooks.json; the hooks are also marked as trusted in ~/.codex/config.toml): Cursor hooks (in ~/.cursor/hooks.json, when ~/.cursor/ exists): OpenCode plugin (~/.config/opencode/plugins/cogniscape.js): Kiro hooks (when ~/.kiro/ exists): Each Stop records the agent’s final answer for that turn, plus tool counts, the model, and credits where Kiro provides them. The Kiro IDE runs hooks only in trusted workspaces — trust the project folder and restart the IDE. On the Kiro CLI v2 engine, the built-in default agent does not support hooks and is not captured; use kiro-cli chat --v3. No agent gets a prompt-submission hook: your prompts are never captured.

​
cogniscape uninstall

Remove hooks and the binary.
Removes the Cogniscape hooks of all five agents (the files listed above, including every Claude Code profile it installed into), sends any events still waiting on the machine, and deletes ~/.cogniscape/ and the binary. A configuration file that is not valid JSON is left untouched and listed in the report. Idempotent. On Windows, the binary cannot be self-deleted while running — the report lists the path for manual removal.

​
cogniscape version

​
cogniscape config show

Prints the config file path, the API URL, and the customer key masked to its last 4 characters. The full key is never printed.

​
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