CLI Commands - Cogniscape

Onboarding commands

`cogniscape init`

Save your customer key to the machine-level config.

cogniscape init <customer-key>

customer-key

string

required

Your Cogniscape customer key. Find it in the Cogniscape dashboard under Settings → API Keys.

What it does:

Creates ~/.cogniscape/config.json

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

Installs Claude Code hooks

Merges Cogniscape hooks into ~/.claude/settings.json automatically.

Running cogniscape init again overwrites the existing key (idempotent). Any existing api_url override is preserved.

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`

Update the customer key for the current project.

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.

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.

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.

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

`cogniscape uninstall`

Remove hooks and the binary.

cogniscape uninstall

Removes Cogniscape hooks from ~/.claude/settings.json and deletes the binary. Idempotent.

Hook adapter

`cogniscape send-episode`

High-level command used by Claude Code hooks. Reads the hook payload from stdin, enriches it with local context, and posts a normalized event to the API.

cogniscape send-episode --event <event-name> [--customer-key <key>] [--api-url <url>]

--event

string

required

The event name to send. See supported events below.

--customer-key

string

Override the customer key. Defaults to ~/.cogniscape/config.json.

--api-url

string

Override the API base URL. Defaults to https://server.cogniscape.app.

Supported events:

`--event` value	What it captures
`session-start`	Session lifecycle begin; records session ID and working directory
`plan-approved`	Plan approval via `ExitPlanMode`; extracts allowed prompts as plan steps
`task-created`	Task creation; caches subject/description for `task-completed` correlation
`task-completed`	Task completion; retrieves cached metadata to build a rich event
`session-summary`	Session end; reads the transcript for a summary and sums token usage

send-episode never fails loudly — all errors are logged to ~/.cogniscape/hooks.log and the process exits with code 0. This ensures Claude Code’s workflow is never blocked by telemetry failures.

Writer commands

Low-level commands for writing directly to the knowledge graph.

`cogniscape writer add-episode`

Write an explicit episode.

cogniscape writer add-episode \
  --name "task_completed:auth-refactor" \
  --body '{"summary":"completed auth refactor","files":["api/auth.py"]}' \
  --group-id "project-alpha" \
  --customer-key <key>

Flag	Required	Description
`--name`	Yes	Episode name
`--body`	No	Episode body (text or JSON); mutually exclusive with `--body-file`
`--body-file`	No	Path to a file containing the episode body
`--group-id`	No	Scope/tenant group
`--reference-time`	No	ISO 8601 timestamp
`--source-description`	No	Source label (default: `cogniscapeibility-cli`)
`--customer-key`	Yes	Customer key (or `COGNISCAPE_CUSTOMER_KEY` env var)
`--api-url`	No	Override API base URL

If --body and --body-file are both omitted, the body is read from stdin.

`cogniscape writer add-facts`

Create an explicit relationship triplet (source → relationship → target).

cogniscape writer add-facts \
  --source "dev:fabio" \
  --relationship "COMMITTED" \
  --target "commit:abc1234" \
  --description "Fabio committed abc1234 in auth module" \
  --customer-key <key>

Flag	Required	Description
`--source`	Yes	Source entity name
`--relationship`	Yes	Relationship label
`--target`	Yes	Target entity name
`--description`	Yes	Fact description
`--group-id`	No	Scope/tenant group
`--source-entity-uuid`	No	Existing source entity UUID
`--target-entity-uuid`	No	Existing target entity UUID
`--customer-key`	Yes	Customer key (or `COGNISCAPE_CUSTOMER_KEY` env var)
`--api-url`	No	Override API base URL

`cogniscape writer add-entity`

Create an entity by writing a synthetic descriptive episode.

cogniscape writer add-entity \
  --name "Authentication Module" \
  --type "Component" \
  --summary "JWT auth layer for API" \
  --customer-key <key>

Flag	Required	Description
`--name`	Yes	Entity name
`--type`	No	Entity type label
`--summary`	No	Entity summary
`--group-id`	No	Scope/tenant group
`--customer-key`	Yes	Customer key (or `COGNISCAPE_CUSTOMER_KEY` env var)
`--api-url`	No	Override API base URL

Configuration

cogniscape config show              # Show full resolved configuration
cogniscape config get api-url       # Show configured API URL
cogniscape config set api-url <url> # Persist API base URL

`cogniscape version`

cogniscape version
# cogniscape (go) v0.1.0

Authentication

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

--customer-key flag
COGNISCAPE_CUSTOMER_KEY environment variable
~/.cogniscape/config.json (machine-level, set by cogniscape init)
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.

Setup

Commands

​Onboarding commands

​cogniscape init

​cogniscape update-key

​cogniscape setup-hooks

​cogniscape uninstall

​Hook adapter

​cogniscape send-episode

​Writer commands

​cogniscape writer add-episode

​cogniscape writer add-facts

​cogniscape writer add-entity

​Configuration

​cogniscape version

​Authentication

​Local files

Onboarding commands

`cogniscape init`

`cogniscape update-key`

`cogniscape setup-hooks`

`cogniscape uninstall`

Hook adapter

`cogniscape send-episode`

Writer commands

`cogniscape writer add-episode`

`cogniscape writer add-facts`

`cogniscape writer add-entity`

Configuration

`cogniscape version`

Authentication

Local files