${provider} CLI found but --version failed (exit ${(err as {

Error message

${provider} CLI found but --version failed (exit ${(err as { status?: number }).status ?? '?'}). Ensure it is authenticated: run `${COMMANDS[provider]} --version` manually.

What it means

detectLocalCLI(provider) found the binary (so not ENOENT) but running `<command> --version` via execFileSync exited non-zero — almost always 'installed but not authenticated'. The provider (claude | codex | opencode) is cached as null, so wiki generation will not attempt to use that CLI and falls back elsewhere. The message names the exact manual command to run.

Source

Thrown at gitnexus/src/core/wiki/local-cli-client.ts:79

    logger.info({ provider, args }, '[local-cli]');
  }
}

const cachedCommands = new Map<LocalAgentProvider, LocalCommand | null>();

export function detectLocalCLI(provider: LocalAgentProvider): string | null {
  if (cachedCommands.has(provider)) return cachedCommands.get(provider)?.displayName ?? null;
  const commandInfo = resolveLocalCommand(provider);
  try {
    execFileSync(commandInfo.command, [...commandInfo.argsPrefix, '--version'], {
      stdio: 'ignore',
    });
    cachedCommands.set(provider, commandInfo);
  } catch (err: unknown) {
    const isNotFound =
      err instanceof Error && 'code' in err && (err as NodeJS.ErrnoException).code === 'ENOENT';
    if (!isNotFound && err instanceof Error) {
      logger.warn(
        `${provider} CLI found but --version failed (exit ${(err as { status?: number }).status ?? '?'}). ` +
          `Ensure it is authenticated: run \`${COMMANDS[provider]} --version\` manually.`,
      );
    }
    cachedCommands.set(provider, null);
  }
  return cachedCommands.get(provider)?.displayName ?? null;
}

export function resolveLocalCLIConfig(overrides?: Partial<LocalCLIConfig>): LocalCLIConfig {
  return {
    model: overrides?.model,
    workingDirectory: overrides?.workingDirectory,
    requestTimeoutMs: overrides?.requestTimeoutMs,
  };
}

export async function callClaudeLLM(

View on GitHub (pinned to 52924ef12c)

Solutions

Run exactly what the message suggests: `claude --version` / `codex --version` / `opencode --version` manually and complete the authentication flow it triggers.
Verify the binary on PATH is the real CLI (`which claude`) and works in a non-TTY shell.
Reinstall or upgrade the provider CLI if --version crashes for non-auth reasons.
Alternatively configure wiki generation to use a provider/model that does not need the local CLI.

Example fix

# before: 'claude CLI found but --version failed (exit 1). Ensure it is authenticated'
claude           # complete login
claude --version  # verify it now exits 0
npx gitnexus wiki  # after: detection succeeds

Defensive patterns

Strategy: validation

Validate before calling

// Before wiki generation: fail fast with an actionable message
import { detectLocalCLI } from 'gitnexus/dist/core/wiki/local-cli-client.js';
for (const provider of ['claude', 'codex', 'opencode'] as const) {
  if (configured(provider) && !detectLocalCLI(provider)) {
    throw new Error(`${provider} CLI unusable — run \`${provider} --version\` and authenticate first`);
  }
}

Type guard

function isAuthExitFailure(err: unknown): boolean {
  return err instanceof Error && 'status' in err &&
    (err as NodeJS.ErrnoException).code !== 'ENOENT'; // found, but exited non-zero
}

Prevention

Authenticate provider CLIs in CI images before wiki jobs (`claude --version` exits 0 when ready).
Cache invalidation: detection caches null — restart the process after authenticating.
Prefer explicit provider/model config that avoids the local CLI when auth is impossible.

When it happens

Trigger: Wiki generation with a local provider configured; resolveLocalCommand succeeds, execFileSync(command, [...argsPrefix, '--version'], { stdio: 'ignore' }) throws with a status code (non-zero exit) and code !== 'ENOENT'. Typical: CLI never logged in, expired credentials, broken install that fails before printing a version.

Common situations: Fresh machines with CLIs installed but not authenticated; CI environments without credential stores; token expiry between runs; wrapper scripts (nvm shims, homebrew) exiting non-zero in non-TTY contexts.

Understand the failure class

Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

AI-assisted analysis of abhigyanpatwari/GitNexus@52924ef12c (2026-08-20). Data as JSON: /api/errors/4ee0474351e4fc57. Report an issue: GitHub.