# List all providers and their availability
npx @visulima/find-ai-runner list

# Output as JSON
npx @visulima/find-ai-runner list --json

# Detect a specific provider
npx @visulima/find-ai-runner detect claude

# Run a prompt against a provider
npx @visulima/find-ai-runner run claude "Explain this error"

# Run with a custom model and timeout
npx @visulima/find-ai-runner run claude "Analyze this code" --model claude-opus-4-20250514 --timeout 60000

# Preview CLI arguments without executing
npx @visulima/find-ai-runner args claude "Explain this code"
npx @visulima/find-ai-runner args claude "Explain this code" --json

import { detectAllProviders } from "@visulima/find-ai-runner";

const all = detectAllProviders();

for (const provider of all) {
    console.log(`${provider.name}: ${provider.available ? "installed" : "not found"}`);
}

import { detectAvailableProviders } from "@visulima/find-ai-runner";

const available = detectAvailableProviders();
console.log(available);
// [{ name: "claude", available: true, path: "/usr/local/bin/claude", version: "1.2.3" }, ...]

import { detectProvider } from "@visulima/find-ai-runner";

const claude = detectProvider("claude");

if (claude.available) {
    console.log(`Claude found at ${claude.path}, version ${claude.version}`);
    console.log(`Detection method: ${claude.detectionMethod}`); // "envvar", "which", or "known-path"
}

import { detectAllProvidersAsync } from "@visulima/find-ai-runner";

const providers = await detectAllProvidersAsync({ version: false });

import { findRunner } from "@visulima/find-ai-runner";

// Prefer claude, then codex, then gemini; stops at the first installed one.
const runner = findRunner(["claude", "codex", "gemini"]);

if (runner) {
    console.log(`Using ${runner.name} at ${runner.path}`);
}

import { detectProvider, runProvider } from "@visulima/find-ai-runner";

const provider = detectProvider("claude");

if (provider.available) {
    const result = await runProvider(provider, "Explain this error: TypeError: Cannot read property 'foo' of undefined");
    console.log(result.stdout);
    console.log(`exit ${result.exitCode} in ${result.durationMs}ms`);
}

import { AiRunError, detectProvider, runProvider } from "@visulima/find-ai-runner";

const provider = detectProvider("claude");
const controller = new AbortController();

if (provider.available) {
    try {
        const result = await runProvider(provider, "Review the staged changes", {
            cwd: "/path/to/repo", // point the agent at a target repo
            env: { ANTHROPIC_API_KEY: process.env.MY_KEY }, // per-run env, merged over process.env
            signal: controller.signal, // controller.abort() cancels the run
            onStdout: (chunk) => process.stdout.write(chunk), // stream progress
        });

        console.log(result.stdout);
    } catch (error) {
        if (error instanceof AiRunError) {
            // Partial output + exit metadata are preserved for debugging.
            console.error(`timedOut=${error.timedOut} aborted=${error.aborted} exit=${error.exitCode}`);
            console.error(error.stdout);
        }
    }
}

import { detectProvider, runProvider } from "@visulima/find-ai-runner";

const provider = detectProvider("claude");

if (provider.available) {
    const result = await runProvider(provider, "Analyze this dependency update", {
        model: "claude-opus-4-20250514",
        maxTokens: 8192,
        timeoutMs: 60_000,
    });

    console.log(result.stdout);
    console.log(`Provider used: ${result.provider}`);
}

import { buildCliArgs } from "@visulima/find-ai-runner";

const args = buildCliArgs("claude", "Explain this code", {
    model: "claude-opus-4-20250514",
});

console.log(args);
// ["--model", "claude-opus-4-20250514", "--output-format", "text", "-p", "Explain this code"]

// With dangerous: true, the permission-bypass flag is prepended:
const unsafe = buildCliArgs("claude", "Explain this code", { dangerous: true });
// ["--dangerously-skip-permissions", "--output-format", "text", "-p", "Explain this code"]

export CLAUDE_PATH=/custom/path/to/claude
export GEMINI_PATH=/opt/custom/gemini