Skip to main content

​
Syntax

gitnexus query <search_query>

​
Description

Searches the knowledge graph for execution flows related to a concept. This is a direct CLI wrapper for the query MCP tool, bypassing MCP overhead for use in scripts, CI, and evaluation. Results are grouped by execution flows (processes), showing how the matched symbols participate in call chains.

​
Arguments

​
search_query
string
required
The concept to search for (e.g., “authentication flow”, “database connection”, “error handling”).

​
Options

​
--repo
string
Target repository name. Omit if only one repository is indexed.Example: --repo my-app
​
--context
string
Task context to improve ranking (e.g., “debugging login failures”).
​
--goal
string
What you want to find (e.g., “find where auth tokens are validated”).
​
--limit
number
Maximum number of processes to return.Default: 5
​
--content
boolean
Include full symbol source code in results.Default: false

​
Usage Examples

gitnexus query "authentication flow"

​
Search with context

gitnexus query "database connection" --context "debugging connection pool leaks"

​
Search with goal

gitnexus query "error handling" --goal "find where exceptions are caught and logged"

​
Search specific repository

gitnexus query "payment processing" --repo backend-api

​
Include source code

gitnexus query "JWT validation" --content

​
Limit results

gitnexus query "API routes" --limit 10

​
Output Format

Results are returned as JSON on stderr (because KuzuDB captures stdout at the OS level): 
{
  "processes": [
    {
      "name": "user_authentication_flow",
      "entry_point": "login",
      "steps": [
        {
          "symbol": "validateCredentials",
          "file": "src/auth/validator.ts",
          "line": 42,
          "type": "Function"
        },
        {
          "symbol": "generateToken",
          "file": "src/auth/token.ts",
          "line": 18,
          "type": "Function"
        }
      ],
      "relevance_score": 0.92
    }
  ],
  "total_results": 3
}

​
When to Use

Use gitnexus query instead of the MCP tool when:
  • Writing shell scripts
  • Running in CI/CD pipelines
  • Performing batch analysis
  • Evaluating GitNexus (e.g., SWE-bench)
  • You need machine-readable output
For interactive use in AI editors, the MCP tool is preferred (better integration with agent workflows).

​
Multi-Repo Support

If you have multiple repositories indexed, specify which one to query: 
gitnexus query "auth" --repo my-app
If you omit --repo with multiple repos indexed, you’ll get an error: 
Error: Multiple repos indexed. Specify --repo <name>

​
Output Destination

All output goes to stderr instead of stdout because KuzuDB’s native module captures stdout at the OS level during initialization. To redirect to a file: 
gitnexus query "auth" 2> results.json

Build docs developers (and LLMs) love

Get started for freeTalk to us