abhigyanpatwari/GitNexus · error · Error

Cursor CLI not found. Install it from https://cursor.com/doc

Error message

Cursor CLI not found. Install it from https://cursor.com/docs/cli/installation

What it means

Thrown by `callCursorLLM` when `detectCursorCLI()` returns null — the `agent` binary was not found in `PATH`. The detection runs `agent --version` via `execSync` and caches the result; if the command fails for any reason (not installed, not in PATH, permission denied), the cache stores null and all subsequent calls to `callCursorLLM` throw immediately. This is a hard dependency for wiki generation when the Cursor LLM provider is selected.

Source

Thrown at gitnexus/src/core/wiki/cursor-client.ts:72

    workingDirectory: overrides?.workingDirectory,
  };
}

/**
 * Call the Cursor CLI in print mode.
 *
 * Uses `agent -p --output-format text` for clean non-streaming output.
 * The prompt is passed as the final CLI argument.
 */
export async function callCursorLLM(
  prompt: string,
  config: CursorConfig,
  systemPrompt?: string,
  options?: CallLLMOptions,
): Promise<LLMResponse> {
  const cursorBin = detectCursorCLI();
  if (!cursorBin) {
    throw new Error(
      'Cursor CLI not found. Install it from https://cursor.com/docs/cli/installation',
    );
  }

  // Always use text format to get clean output without agent narration/thinking.
  // stream-json captures assistant messages which include "Let me explore..." narration
  // that pollutes the actual content when using thinking models.
  const fullPrompt = systemPrompt ? `${systemPrompt}\n\n---\n\n${prompt}` : prompt;

  const args = ['-p', '--output-format', 'text'];

  if (config.model) {
    args.push('--model', config.model);
  }

  // Add the prompt as the final argument
  args.push(fullPrompt);

View on GitHub (pinned to d540b00184)

Solutions

Install the Cursor CLI from the URL in the error message (https://cursor.com/docs/cli/installation).
Verify the binary is on PATH: run `agent --version` in the same shell/environment where `gitnexus wiki` runs.
If already installed, ensure the directory containing the `agent` binary is in `PATH` for the process running GitNexus.
If the detection was cached as null in a long-lived process (e.g., `gitnexus serve`), restart the process after installing the CLI.

Example fix

# before
# agent binary not installed
gitnexus wiki --llm cursor
# error: Cursor CLI not found. Install it from https://cursor.com/docs/cli/installation
# after
# install Cursor CLI per the docs
agent --version  # verify it's on PATH
gitnexus wiki --llm cursor

Defensive patterns

Strategy: validation

Validate before calling

// Before wiki generation with the Cursor provider, verify the CLI is available:
import { detectCursorCLI } from './wiki/cursor-client.js';
if (!detectCursorCLI()) {
  console.error('Cursor CLI (agent) not found. Install it first.');
  process.exit(1);
}

Type guard

import { detectCursorCLI } from './wiki/cursor-client.js';
const isCursorCliAvailable = (): boolean => detectCursorCLI() !== null;

Try / catch

try {
  await callCursorLLM(prompt, config, systemPrompt);
} catch (err) {
  if (err instanceof Error && err.message.includes('Cursor CLI not found')) {
    console.error('Install the Cursor CLI from https://cursor.com/docs/cli/installation');
    console.error('Verify with: agent --version');
  }
  throw err;
}

Prevention

Run `agent --version` in the target environment before relying on the Cursor wiki provider.
Note that `detectCursorCLI` caches its result module-level — restart long-lived processes after installing the CLI.
Consider using a different LLM provider (OpenAI-compatible) if the Cursor CLI is unavailable in your environment.

When it happens

Trigger: Wiki generation is configured to use the Cursor CLI as its LLM backend (`callCursorLLM` is invoked), but `execSync('agent --version', { stdio: 'ignore' })` threw — the `agent` binary is not installed or not on PATH.

Common situations: Cursor CLI was never installed; it's installed but not on the shell's PATH (common in GUI-launched apps or non-interactive shells); the binary exists but lacks execute permission; a stale cache from a previous failed detection in a long-lived process (the cache is module-level and never invalidated).

Related errors

AI-assisted analysis of abhigyanpatwari/GitNexus@d540b00184 (2026-08-12). Data as JSON: /api/errors/36858914eb518e38. Report an issue: GitHub.