Build repository graphs once, query them with precision.

Authenticate the CLI with your graphchat server using an API key (prefix sk-graphchat-). Exchanges the key for a JWT access + refresh token pair stored locally. The token is auto-refreshed before expiry.

gph login --key sk-graphchat-abc123
gph login --key sk-graphchat-abc123 --server https://your.graphchat.host

Revokes the stored refresh token on the server and removes local credentials. After logout, any cached access token is also invalidated.

gph logout

Shows the currently authenticated user, server URL, and token expiry. Use --json for machine-readable output.

gph status
gph status --json

Lists all repositories accessible to the current user. Returns repo ID, name, branch, last sync time, and node count.

gph repos
gph repos --json

Indexes a local repository path and pushes it to the graph service. The path is resolved to an absolute path; only files within it are included. Reuses prior state so only changed files are re-processed.

gph index ./src --repo my-api-id
gph index . --repo backend --branch main

Vector + graph search across indexed repos. The --budget flag caps the token count of returned results, dropping lower-confidence nodes first. --agent emits a compact format ready to paste into an AI chat prompt. --confidence accepts EXTRACTED | INFERRED | SPECULATIVE.

gph search "authentication middleware" --budget 1500
gph search "JWT guard" --repo backend --confidence EXTRACTED --agent

Graph-expanded retrieval. Embeds your natural-language question, runs vector KNN to pick seed nodes, then traverses the graph from those seeds. --mode knn (default) returns neighbours by similarity; bfs / dfs walk structural edges. --hops controls expansion depth, --budget caps the response in tokens.

gph query "how does login work?" --repo my-api-id
gph query "request lifecycle" --repo backend --mode bfs --hops 3 --budget 3000

AI-generated explanation of a single node, grounded in the graph. The CLI looks up the node by label (case-insensitive exact match), pulls its strongest neighbours, and asks the configured LLM to describe what it is, how it relates to those neighbours, and any caveats. Uses your active LLM provider from Settings → Model.

gph explain AuthService --repo my-api-id
gph explain ResponseInterceptor --repo backend

Finds the shortest path between two named symbols in the graph and prints every hop. Useful for understanding how middleware or dependency chains connect.

gph path AuthService JwtGuard --repo my-api-id
gph path ResponseInterceptor DatabaseService --repo backend

Keeps the graph in sync with a working directory. Default mode runs a local file watcher (chokidar) and re-indexes after a debounce window — only the diff is uploaded; source code stays on your machine. With --on-commit, installs idempotent post-commit / post-checkout / post-merge git hooks that re-index in the background. Use --stop with --on-commit to remove the hooks.

gph watch ./src --repo my-api-id
gph watch ./src --repo my-api-id --debounce 3000
gph watch ./src --repo my-api-id --on-commit
gph watch ./src --repo my-api-id --stop

Generates a GRAPH_REPORT.md audit report summarising god nodes, top communities, surprise edges, and file coverage stats. Ready to paste into a PR description or agent prompt.

gph report --repo my-api-id --out GRAPH_REPORT.md
gph report --repo backend --out ./reports/backend.md

Exports a full agent context payload for a named repo as a structured JSON bundle. The bundle includes graph metadata, communities, nodes, and edges — ready to feed into any LLM session.

gph export --repo my-api-id --out context.json
gph export --repo backend --out ./context/backend.json