Reference CLI

CLI Reference

Server mode (default)

Start the HTTP server:

claudegql

Configuration is via environment variables. Prints the listening addresses on startup:

server:     http://localhost:8765/graphql
playground: http://localhost:8765/playground
hook:       POST http://localhost:8765/hook
docs:       http://localhost:8765/docs

Record mode

Read hook JSON from stdin and forward to the server:

claudegql record

This is the command Claude Code calls for each hook event. It silently exits on any error (network failure, server not running, etc.) so it never blocks Claude Code.

Query mode

Run a GraphQL query against the local server/store and print JSON:

claudegql query '{ sessions(limit:5) { id status cwd model lastSeenAt } }'

Useful session-intelligence examples:

# Skills actually used by recent sessions
claudegql query '{ sessions(limit:10) { id skillsUsed { name count } } }'

# Subagents spawned and their assignments
claudegql query '{ sessions(limit:5) { id subagents { agentType description } } }'

# Edited files and user prompts
claudegql query '{ sessions(limit:5) { id editedFiles prompts } }'

# Search captured prompts, tool inputs, and tool outputs
claudegql query '{ search(query:"webhook", limit:5) { matchField snippet hook { sessionId toolName recordedAt } } }'

Schema mode

Print the compact GraphQL schema:

claudegql schema

The schema output omits descriptions and is designed for quick terminal inspection or pasting into an LLM context before asking it to design queries.

install-hooks

Write hook configuration into ~/.claude/settings.json:

claudegql install-hooks

With a custom binary path (useful after moving the binary):

claudegql install-hooks --binary /path/to/claudegql

Registers hooks for: PreToolUse, PostToolUse, Stop, SubagentStop, Notification, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, PostCompact.

Running it again is safe — already-registered hooks are skipped.

Make targets

Target	Description
make build	Build bin/claudegql
make run	Build + run in foreground
make run-bg	Build + run in background (logs → claudegql.log)
make stop	Kill the server on port 8765
make install-hooks	Build + register hooks in ~/.claude/settings.json
make generate	Regenerate gqlgen code after schema changes
make record-test	Send a test hook event to the running server