agentaudit 3.9.18 → 3.9.20

package/README.md

@@ -208,6 +208,7 @@ Then ask your agent: *"Check which MCP servers I have installed and audit any un
 | `agentaudit audit <url>` | Deep LLM-powered 3-pass audit (~30s) | `agentaudit audit https://github.com/owner/repo` |
 | `agentaudit lookup <name>` | Look up package in trust registry | `agentaudit lookup fastmcp` |
 | `agentaudit check <name\|url>` | Lookup + auto-audit if not found | `agentaudit check https://github.com/owner/repo` |
+| `agentaudit status` | Check API keys + active LLM provider | `agentaudit status` |
 | `agentaudit setup` | Register agent + configure API key | `agentaudit setup` |
 
 ### Global Flags
@@ -217,6 +218,7 @@ Then ask your agent: *"Check which MCP servers I have installed and audit any un
 | `--json` | Output machine-readable JSON to stdout |
 | `--quiet` / `-q` | Suppress banner and decorative output (show findings only) |
 | `--no-color` | Disable ANSI colors (also respects `NO_COLOR` env var) |
+| `--provider <name>` | Force LLM provider (`anthropic`, `openai`, `openrouter`, `ollama`, `custom`) |
 | `--help` / `-h` | Show help text |
 | `-v` / `--version` | Show version |
 
@@ -433,12 +435,19 @@ export AGENTAUDIT_API_KEY=asf_your_key_here
 | Variable | Description |
 |----------|-------------|
 | `AGENTAUDIT_API_KEY` | API key for registry access |
-| `ANTHROPIC_API_KEY` | Anthropic API key for deep audits (Claude) |
+| `ANTHROPIC_API_KEY` | Anthropic API key for deep audits (Claude) -- recommended |
 | `OPENAI_API_KEY` | OpenAI API key for deep audits (GPT-4o) |
 | `OPENROUTER_API_KEY` | OpenRouter API key (access 200+ models) |
 | `OPENROUTER_MODEL` | Model to use via OpenRouter (default: `anthropic/claude-sonnet-4`) |
+| `OLLAMA_MODEL` | Ollama model name for local audits (e.g. `llama3.1`, `qwen2.5-coder`) |
+| `OLLAMA_HOST` | Ollama server URL (default: `http://localhost:11434`) |
+| `LLM_API_URL` | Any OpenAI-compatible API endpoint (e.g. LM Studio, vLLM, Together, Groq) |
+| `LLM_API_KEY` | API key for custom endpoint (optional if no auth needed) |
+| `LLM_MODEL` | Model name for custom endpoint |
 | `NO_COLOR` | Disable ANSI colors ([no-color.org](https://no-color.org)) |
 
+> **Provider priority:** Anthropic > OpenAI > OpenRouter > Custom > Ollama. Override with `--provider=ollama` etc.
+
 ---
 
 ## 📦 Requirements
@@ -468,7 +477,7 @@ Or use without installing: `npx agentaudit`
 
 ### Setting up your LLM key for deep audits
 
-The `audit` command supports **three LLM providers**. Set one of these environment variables:
+The `audit` command supports **any LLM provider**. Set one of these environment variables:
 
 ```bash
 # Linux / macOS
@@ -487,13 +496,32 @@ set OPENAI_API_KEY=sk-...
 set OPENROUTER_API_KEY=sk-or-...
 ```
 
-**Provider priority:** Anthropic > OpenAI > OpenRouter. The active provider is shown during the audit.
+**Provider priority:** Anthropic > OpenAI > OpenRouter > Custom > Ollama. Override with `--provider=<name>`.
 
-**OpenRouter model selection:** By default, OpenRouter uses `anthropic/claude-sonnet-4`. Override with:
+**OpenRouter model selection:** By default uses `anthropic/claude-sonnet-4`. Override with:
 ```bash
 export OPENROUTER_MODEL=google/gemini-2.5-pro    # or any model on openrouter.ai
 ```
 
+**Local with Ollama (free, no API key):**
+```bash
+export OLLAMA_MODEL=llama3.1          # or qwen2.5-coder, deepseek-r1, etc.
+agentaudit audit https://github.com/owner/repo
+```
+> Note: Local models produce lower quality audits than Claude/GPT-4o. Use for quick checks, not production security audits.
+
+**Any OpenAI-compatible API:**
+```bash
+export LLM_API_URL=http://localhost:1234/v1     # LM Studio, vLLM, etc.
+export LLM_MODEL=my-model
+agentaudit audit https://github.com/owner/repo
+```
+
+**Check your setup:**
+```bash
+agentaudit status    # validates all configured API keys
+```
+
 **Troubleshooting:** If you see `API error: Incorrect API key`, double-check your key is valid and has credits. Use `--debug` to see the full API response.
 
 ### What data is sent externally?

package/cli.mjs

@@ -1,18 +1,12 @@
 #!/usr/bin/env node
 /**
- * AgentAudit CLI — Security scanner for AI packages
+ * AgentAudit CLI — Security scanner for AI tools
  * 
- * Usage:
- *   agentaudit                                     Discover local MCP servers
- *   agentaudit discover [--quick|--deep]            Find MCP servers in AI editors
- *   agentaudit scan <repo-url> [--deep]             Quick scan (or deep audit with --deep)
- *   agentaudit audit <repo-url>                     Deep LLM-powered security audit
- *   agentaudit lookup <name>                        Look up package in registry
- *   agentaudit check <name|url>                     Lookup + auto-audit if not found
- *   agentaudit status                               Check configured API keys + providers
- *   agentaudit setup                                Register + configure API key
+ * Scan & Audit:  scan <url>, audit <url>, discover
+ * Registry:      check <name|url>, lookup <name>
+ * Setup:         status, setup, config
  * 
- * Global flags: --json, --quiet, --no-color
+ * Global flags: --json, --quiet, --no-color, --provider, --debug, --export
  */
 
 import fs from 'fs';
@@ -27,23 +21,38 @@ const SKILL_DIR = path.resolve(__dirname);
 const REGISTRY_URL = 'https://agentaudit.dev';
 
 // ── Provider resolution ────
-function resolveProvider(preferred, keys) {
+function resolveProvider(flagOverride, keys) {
+  const orModel = process.env.OPENROUTER_MODEL || 'anthropic/claude-sonnet-4';
+  const ollamaModel = process.env.OLLAMA_MODEL || 'llama3.1';
+  const ollamaHost = process.env.OLLAMA_HOST || 'http://localhost:11434';
+  const customUrl = process.env.LLM_API_URL;
+  const customKey = process.env.LLM_API_KEY;
+  const customModel = process.env.LLM_MODEL || 'default';
+
   const providers = {
     anthropic: keys.anthropicKey ? { id: 'anthropic', label: 'Anthropic (Claude)', key: keys.anthropicKey } : null,
     openai: keys.openaiKey ? { id: 'openai', label: 'OpenAI (GPT-4o)', key: keys.openaiKey } : null,
-    openrouter: keys.openrouterKey ? { id: 'openrouter', label: `OpenRouter (${process.env.OPENROUTER_MODEL || 'anthropic/claude-sonnet-4'})`, key: keys.openrouterKey } : null,
+    openrouter: keys.openrouterKey ? { id: 'openrouter', label: `OpenRouter (${orModel})`, key: keys.openrouterKey } : null,
+    ollama: process.env.OLLAMA_MODEL || process.env.OLLAMA_HOST ? { id: 'ollama', label: `Ollama (${ollamaModel})`, key: null, host: ollamaHost, model: ollamaModel } : null,
+    custom: customUrl ? { id: 'custom', label: `Custom (${customModel})`, key: customKey, url: customUrl, model: customModel } : null,
   };
   // Aliases
-  const aliases = { claude: 'anthropic', gpt: 'openai', 'gpt-4o': 'openai', 'gpt4': 'openai', or: 'openrouter' };
+  const aliases = { claude: 'anthropic', gpt: 'openai', 'gpt-4o': 'openai', 'gpt4': 'openai', or: 'openrouter', local: 'ollama' };
+
+  // Priority: --provider flag > AGENTAUDIT_PROVIDER env > config file > auto-detect
+  const preferred = flagOverride
+    || process.env.AGENTAUDIT_PROVIDER?.toLowerCase()
+    || loadConfig()?.preferred_provider
+    || null;
 
   if (preferred) {
     const resolved = aliases[preferred] || preferred;
     const p = providers[resolved];
-    if (!p) return null; // requested provider not available
+    if (!p) return null;
     return p;
   }
-  // Auto-detect: Anthropic > OpenAI > OpenRouter
-  return providers.anthropic || providers.openai || providers.openrouter || null;
+  // Auto-detect priority: Anthropic > OpenAI > OpenRouter > Custom > Ollama (local last — usually weaker)
+  return providers.anthropic || providers.openai || providers.openrouter || providers.custom || providers.ollama || null;
 }
 
 // ── Global flags (set in main before command routing) ────
@@ -120,6 +129,24 @@ function saveCredentials(data) {
   } catch {}
 }
 
+const USER_CONFIG_FILE = path.join(USER_CRED_DIR, 'config.json');
+
+function loadConfig() {
+  try {
+    if (fs.existsSync(USER_CONFIG_FILE)) {
+      return JSON.parse(fs.readFileSync(USER_CONFIG_FILE, 'utf8'));
+    }
+  } catch {}
+  return {};
+}
+
+function saveConfig(data) {
+  const existing = loadConfig();
+  const merged = { ...existing, ...data };
+  fs.mkdirSync(USER_CRED_DIR, { recursive: true });
+  fs.writeFileSync(USER_CONFIG_FILE, JSON.stringify(merged, null, 2), { mode: 0o600 });
+}
+
 function askQuestion(question) {
   const rl = createInterface({ input: process.stdin, output: process.stdout });
   return new Promise(resolve => rl.question(question, answer => { rl.close(); resolve(answer.trim()); }));
@@ -303,6 +330,28 @@ async function setupCommand() {
   console.log();
 }
 
+// ── Structured error output ─────────────────────────────
+
+function emitError(code, message, hint, exitCode = 2) {
+  if (jsonMode) {
+    process.stderr.write(JSON.stringify({ error: true, code, message, hint: hint || undefined, exitCode }) + '\n');
+  }
+  process.exitCode = exitCode;
+}
+
+// ── Levenshtein distance for typo correction ────────────
+
+function levenshtein(a, b) {
+  const m = a.length, n = b.length;
+  const dp = Array.from({ length: m + 1 }, () => Array(n + 1).fill(0));
+  for (let i = 0; i <= m; i++) dp[i][0] = i;
+  for (let j = 0; j <= n; j++) dp[0][j] = j;
+  for (let i = 1; i <= m; i++)
+    for (let j = 1; j <= n; j++)
+      dp[i][j] = Math.min(dp[i-1][j] + 1, dp[i][j-1] + 1, dp[i-1][j-1] + (a[i-1] !== b[j-1] ? 1 : 0));
+  return dp[m][n];
+}
+
 // ── Helpers ──────────────────────────────────────────────
 
 function getVersion() {
@@ -315,8 +364,8 @@ function getVersion() {
 function banner() {
   if (quietMode || jsonMode) return;
   console.log();
-  console.log(`  ${c.bold}${c.cyan}AgentAudit${c.reset} ${c.dim}v${getVersion()}${c.reset}`);
-  console.log(`  ${c.dim}Security scanner for AI packages${c.reset}`);
+  console.log(`  🛡  ${c.bold}${c.cyan}AgentAudit${c.reset} ${c.dim}v${getVersion()}${c.reset}`);
+  console.log(`  ${c.dim}Security scanner for AI tools${c.reset}`);
   console.log();
 }
 
@@ -1344,10 +1393,14 @@ async function auditRepo(url) {
   if (!resolvedProvider) {
     // No LLM API key — clear explanation
     console.log();
-    console.log(`  ${c.yellow}No LLM API key found.${c.reset} The ${c.bold}audit${c.reset} command needs an LLM to analyze code.`);
+    console.log(`  ${c.yellow}No LLM provider configured.${c.reset} The ${c.bold}audit${c.reset} command needs an LLM to analyze code.`);
     console.log();
-    console.log(`  ${c.bold}Option 1: Set an API key${c.reset}`);
-    console.log(`  Supported keys: ${c.cyan}ANTHROPIC_API_KEY${c.reset}, ${c.cyan}OPENAI_API_KEY${c.reset}, or ${c.cyan}OPENROUTER_API_KEY${c.reset}`);
+    console.log(`  ${c.bold}Option 1: Set an API key${c.reset} ${c.dim}(any one of these)${c.reset}`);
+    console.log(`  ${c.cyan}ANTHROPIC_API_KEY${c.reset}    Anthropic Claude ${c.dim}(recommended)${c.reset}`);
+    console.log(`  ${c.cyan}OPENAI_API_KEY${c.reset}       OpenAI GPT-4o`);
+    console.log(`  ${c.cyan}OPENROUTER_API_KEY${c.reset}   OpenRouter ${c.dim}(200+ models)${c.reset}`);
+    console.log(`  ${c.cyan}OLLAMA_MODEL${c.reset}         Ollama ${c.dim}(local, free, set model name)${c.reset}`);
+    console.log(`  ${c.cyan}LLM_API_URL${c.reset}          Any OpenAI-compatible API ${c.dim}(+ LLM_API_KEY, LLM_MODEL)${c.reset}`);
     console.log();
     console.log(`  ${c.dim}# Linux / macOS:${c.reset}`);
     console.log(`  ${c.dim}export ANTHROPIC_API_KEY=sk-ant-...${c.reset}`);
@@ -1451,19 +1504,33 @@ async function auditRepo(url) {
       _lastLlmText = text;
       report = extractJSON(text);
     } else {
-      // OpenAI or OpenRouter (both use OpenAI-compatible API)
-      const isOpenRouter = resolvedProvider.id === 'openrouter';
-      const apiUrl = isOpenRouter ? 'https://openrouter.ai/api/v1/chat/completions' : 'https://api.openai.com/v1/chat/completions';
-      const modelName = isOpenRouter ? (process.env.OPENROUTER_MODEL || 'anthropic/claude-sonnet-4') : 'gpt-4o';
-      const extraHeaders = isOpenRouter ? { 'HTTP-Referer': 'https://agentaudit.dev', 'X-Title': 'AgentAudit' } : {};
+      // OpenAI, OpenRouter, Ollama, or Custom (all use OpenAI-compatible chat completions API)
+      let apiUrl, modelName, authHeaders;
+      switch (resolvedProvider.id) {
+        case 'openrouter':
+          apiUrl = 'https://openrouter.ai/api/v1/chat/completions';
+          modelName = process.env.OPENROUTER_MODEL || 'anthropic/claude-sonnet-4';
+          authHeaders = { 'Authorization': `Bearer ${resolvedProvider.key}`, 'HTTP-Referer': 'https://agentaudit.dev', 'X-Title': 'AgentAudit' };
+          break;
+        case 'ollama':
+          apiUrl = `${resolvedProvider.host}/v1/chat/completions`;
+          modelName = resolvedProvider.model;
+          authHeaders = {};
+          break;
+        case 'custom':
+          apiUrl = resolvedProvider.url.endsWith('/chat/completions') ? resolvedProvider.url : `${resolvedProvider.url.replace(/\/$/, '')}/chat/completions`;
+          modelName = resolvedProvider.model;
+          authHeaders = resolvedProvider.key ? { 'Authorization': `Bearer ${resolvedProvider.key}` } : {};
+          break;
+        default: // openai
+          apiUrl = 'https://api.openai.com/v1/chat/completions';
+          modelName = 'gpt-4o';
+          authHeaders = { 'Authorization': `Bearer ${resolvedProvider.key}` };
+      }
 
       const res = await fetch(apiUrl, {
         method: 'POST',
-        headers: {
-          'Authorization': `Bearer ${resolvedProvider.key}`,
-          'Content-Type': 'application/json',
-          ...extraHeaders,
-        },
+        headers: { 'Content-Type': 'application/json', ...authHeaders },
         body: JSON.stringify({
           model: modelName,
           max_tokens: 8192,
@@ -1472,7 +1539,7 @@ async function auditRepo(url) {
             { role: 'user', content: userMessage },
           ],
         }),
-        signal: AbortSignal.timeout(120_000),
+        signal: AbortSignal.timeout(resolvedProvider.id === 'ollama' ? 300_000 : 120_000), // Ollama: 5min (local can be slow)
       });
       const data = await res.json();
       if (data.error) {
@@ -1579,8 +1646,11 @@ async function checkPackage(name) {
         console.log();
         return await auditRepo(name);
       }
-      console.log(`  ${c.yellow}Not found${c.reset} — package "${name}" hasn't been audited yet.`);
-      console.log(`  ${c.dim}Run: agentaudit audit <repo-url> for a deep LLM audit${c.reset}`);
+      console.log(`  ${c.yellow}✖  Not found${c.reset} — "${name}" hasn't been audited yet.`);
+      console.log();
+      console.log(`  ${c.dim}Next steps:${c.reset}`);
+      console.log(`    ${c.cyan}agentaudit audit <repo-url>${c.reset}    ${c.dim}Run a deep audit yourself${c.reset}`);
+      console.log(`    ${c.cyan}agentaudit scan <repo-url>${c.reset}     ${c.dim}Quick static check (no API key)${c.reset}`);
     }
     return null;
   }
@@ -1672,57 +1742,41 @@ async function main() {
   
   if (args[0] === '--help' || args[0] === '-h') {
     banner();
-    console.log(`  ${c.bold}Commands:${c.reset}`);
-    console.log();
-    console.log(`    ${c.cyan}agentaudit${c.reset}                                   Discover MCP servers (same as discover)`);
-    console.log(`    ${c.cyan}agentaudit discover${c.reset}                          Find MCP servers in your AI editors (Cursor, Claude, VS Code, Windsurf)`);
-    console.log(`    ${c.cyan}agentaudit discover --quick${c.reset}                  Discover + auto-scan all servers`);
-    console.log(`    ${c.cyan}agentaudit discover --deep${c.reset}                   Discover + select servers to deep-audit`);
-    console.log(`    ${c.cyan}agentaudit scan${c.reset} <url> [url...]               Quick static scan (regex, local)`);
-    console.log(`    ${c.cyan}agentaudit scan${c.reset} <url> ${c.dim}--deep${c.reset}                Deep audit (same as audit)`);
-    console.log(`    ${c.cyan}agentaudit audit${c.reset} <url> [url...]              Deep LLM-powered security audit`);
-    console.log(`    ${c.cyan}agentaudit lookup${c.reset} <name>                     Look up package in registry`);
-    console.log(`    ${c.cyan}agentaudit check${c.reset} <name|url>                  Lookup + auto-audit if not found`);
-    console.log(`    ${c.cyan}agentaudit status${c.reset}                            Check API keys + active provider`);
-    console.log(`    ${c.cyan}agentaudit setup${c.reset}                             Register + configure API key`);
+    console.log(`  ${c.bold}USAGE${c.reset}`);
+    console.log(`    ${c.cyan}agentaudit${c.reset} <command> [options]`);
     console.log();
-    console.log(`  ${c.bold}Global flags:${c.reset}`);
-    console.log(`    ${c.dim}--json       Output JSON to stdout (machine-readable)${c.reset}`);
-    console.log(`    ${c.dim}--quiet      Suppress banner and tree visualization${c.reset}`);
-    console.log(`    ${c.dim}--no-color   Disable ANSI colors (also: NO_COLOR env)${c.reset}`);
-    console.log(`    ${c.dim}--provider   Force LLM provider (anthropic, openai, openrouter)${c.reset}`);
+    console.log(`  ${c.bold}SCAN & AUDIT${c.reset}`);
+    console.log(`    ${c.cyan}scan${c.reset} <url> [url...]          Quick static analysis ${c.dim}(~2s, no API key)${c.reset}`);
+    console.log(`    ${c.cyan}audit${c.reset} <url> [url...]         Deep LLM security audit ${c.dim}(~30s)${c.reset}`);
+    console.log(`    ${c.cyan}discover${c.reset}                     Find MCP servers in your editors`);
     console.log();
-    console.log(`  ${c.bold}Quick Scan${c.reset} vs ${c.bold}Deep Audit${c.reset}:`);
-    console.log(`    ${c.dim}scan  = fast regex-based static analysis (~2s)${c.reset}`);
-    console.log(`    ${c.dim}audit = deep LLM analysis with 3-pass methodology (~30s)${c.reset}`);
+    console.log(`  ${c.bold}REGISTRY${c.reset}`);
+    console.log(`    ${c.cyan}check${c.reset} <name|url>             Look up or auto-audit package`);
+    console.log(`    ${c.cyan}lookup${c.reset} <name>                Look up package in registry`);
     console.log();
-    console.log(`  ${c.bold}Exit codes:${c.reset}`);
-    console.log(`    ${c.dim}0 = clean / success    1 = findings detected    2 = error${c.reset}`);
+    console.log(`  ${c.bold}SETUP${c.reset}`);
+    console.log(`    ${c.cyan}status${c.reset}                       Check providers & API keys`);
+    console.log(`    ${c.cyan}setup${c.reset}                        Register & configure`);
+    console.log(`    ${c.cyan}config set${c.reset} <key> <value>     Set default provider/options`);
     console.log();
-    console.log(`  ${c.bold}Examples:${c.reset}`);
-    console.log(`    agentaudit`);
-    console.log(`    agentaudit discover --quick`);
-    console.log(`    agentaudit scan https://github.com/owner/repo`);
-    console.log(`    agentaudit audit https://github.com/owner/repo`);
-    console.log(`    agentaudit lookup fastmcp --json`);
+    console.log(`  ${c.bold}OPTIONS${c.reset}`);
+    console.log(`    ${c.dim}--json         Machine-readable JSON output${c.reset}`);
+    console.log(`    ${c.dim}--quiet        Suppress banner${c.reset}`);
+    console.log(`    ${c.dim}--no-color     Disable colors ${c.reset}${c.dim}(also: NO_COLOR=1)${c.reset}`);
+    console.log(`    ${c.dim}--provider <p> Force provider ${c.reset}${c.dim}(anthropic|openai|openrouter|ollama|custom)${c.reset}`);
+    console.log(`    ${c.dim}--export       Export audit payload to markdown${c.reset}`);
+    console.log(`    ${c.dim}--debug        Show raw LLM response on errors${c.reset}`);
     console.log();
-    console.log(`  ${c.bold}For deep audits,${c.reset} set an LLM API key (any one):`);
-    if (process.platform === 'win32') {
-      console.log(`    ${c.dim}PowerShell:  $env:ANTHROPIC_API_KEY = "sk-ant-..."${c.reset}`);
-      console.log(`    ${c.dim}             $env:OPENAI_API_KEY = "sk-..."${c.reset}`);
-      console.log(`    ${c.dim}             $env:OPENROUTER_API_KEY = "sk-or-..."${c.reset}`);
-      console.log(`    ${c.dim}CMD:         set ANTHROPIC_API_KEY=sk-ant-...${c.reset}`);
-      console.log(`    ${c.dim}             set OPENAI_API_KEY=sk-...${c.reset}`);
-      console.log(`    ${c.dim}             set OPENROUTER_API_KEY=sk-or-...${c.reset}`);
-    } else {
-      console.log(`    ${c.dim}export ANTHROPIC_API_KEY=sk-ant-...${c.reset}`);
-      console.log(`    ${c.dim}export OPENAI_API_KEY=sk-...${c.reset}`);
-      console.log(`    ${c.dim}export OPENROUTER_API_KEY=sk-or-...${c.reset}    ${c.dim}(200+ models, set OPENROUTER_MODEL to pick)${c.reset}`);
-    }
+    console.log(`  ${c.bold}EXAMPLES${c.reset}`);
+    console.log(`    ${c.dim}$${c.reset} agentaudit scan https://github.com/owner/repo`);
+    console.log(`    ${c.dim}$${c.reset} agentaudit audit https://github.com/owner/repo`);
+    console.log(`    ${c.dim}$${c.reset} agentaudit check fastmcp`);
+    console.log(`    ${c.dim}$${c.reset} agentaudit status`);
     console.log();
-    console.log(`  ${c.bold}Or use as MCP server${c.reset} in Cursor/Claude ${c.dim}(no extra API key needed):${c.reset}`);
-    console.log(`    ${c.dim}Add to your MCP config:${c.reset}`);
-    console.log(`    ${c.dim}{ "agentaudit": { "command": "npx", "args": ["-y", "agentaudit"] } }${c.reset}`);
+    console.log(`  ${c.bold}PROVIDERS${c.reset} ${c.dim}(set any one for deep audits)${c.reset}`);
+    console.log(`    ${c.dim}ANTHROPIC_API_KEY · OPENAI_API_KEY · OPENROUTER_API_KEY · OLLAMA_MODEL · LLM_API_URL${c.reset}`);
+    console.log(`    ${c.dim}Set default: AGENTAUDIT_PROVIDER=openai or agentaudit config set provider openai${c.reset}`);
+    console.log(`    ${c.dim}Run ${c.cyan}agentaudit status${c.dim} to check configuration.${c.reset}`);
     console.log();
     process.exitCode = 0; return;
   }
@@ -1746,10 +1800,16 @@ async function main() {
       openaiKey: process.env.OPENAI_API_KEY,
       openrouterKey: process.env.OPENROUTER_API_KEY,
     };
+    const ollamaHost = process.env.OLLAMA_HOST || 'http://localhost:11434';
+    const ollamaModel = process.env.OLLAMA_MODEL;
+    const customUrl = process.env.LLM_API_URL;
+
     const checks = [
       { name: 'Anthropic', env: 'ANTHROPIC_API_KEY', key: keys.anthropicKey, testUrl: 'https://api.anthropic.com/v1/messages', testHeaders: (k) => ({ 'x-api-key': k, 'anthropic-version': '2023-06-01', 'content-type': 'application/json' }), testBody: JSON.stringify({ model: 'claude-sonnet-4-20250514', max_tokens: 1, messages: [{ role: 'user', content: 'hi' }] }) },
-      { name: 'OpenAI', env: 'OPENAI_API_KEY', key: keys.openaiKey, testUrl: 'https://api.openai.com/v1/models', testHeaders: (k) => ({ 'Authorization': `Bearer ${k}` }), testBody: null },
-      { name: 'OpenRouter', env: 'OPENROUTER_API_KEY', key: keys.openrouterKey, testUrl: 'https://openrouter.ai/api/v1/models', testHeaders: (k) => ({ 'Authorization': `Bearer ${k}` }), testBody: null },
+      { name: 'OpenAI', env: 'OPENAI_API_KEY', key: keys.openaiKey, testUrl: 'https://api.openai.com/v1/chat/completions', testHeaders: (k) => ({ 'Authorization': `Bearer ${k}`, 'Content-Type': 'application/json' }), testBody: JSON.stringify({ model: 'gpt-4o-mini', max_tokens: 1, messages: [{ role: 'user', content: 'hi' }] }) },
+      { name: 'OpenRouter', env: 'OPENROUTER_API_KEY', key: keys.openrouterKey, testUrl: 'https://openrouter.ai/api/v1/chat/completions', testHeaders: (k) => ({ 'Authorization': `Bearer ${k}`, 'Content-Type': 'application/json', 'HTTP-Referer': 'https://agentaudit.dev', 'X-Title': 'AgentAudit' }), testBody: JSON.stringify({ model: 'openai/gpt-4o-mini', max_tokens: 1, messages: [{ role: 'user', content: 'hi' }] }) },
+      { name: 'Ollama', env: 'OLLAMA_MODEL', key: ollamaModel, testUrl: `${ollamaHost}/api/tags`, testHeaders: () => ({}), testBody: null },
+      { name: 'Custom', env: 'LLM_API_URL', key: customUrl, testUrl: customUrl ? `${customUrl.replace(/\/$/, '')}/models` : null, testHeaders: (k) => process.env.LLM_API_KEY ? ({ 'Authorization': `Bearer ${process.env.LLM_API_KEY}` }) : {}, testBody: null },
     ];
 
     for (const p of checks) {
@@ -1770,8 +1830,25 @@ async function main() {
           process.stdout.write(`\r    ${c.green}●${c.reset}  ${p.name.padEnd(12)} ${c.dim}${masked}${c.reset}  ${c.green}valid ✓${c.reset}  \n`);
         } else {
           const body = await res.json().catch(() => ({}));
-          const errMsg = body?.error?.message || `HTTP ${res.status}`;
-          process.stdout.write(`\r    ${c.red}●${c.reset}  ${p.name.padEnd(12)} ${c.dim}${masked}${c.reset}  ${c.red}invalid ✗${c.reset} ${c.dim}(${errMsg})${c.reset}  \n`);
+          const rawMsg = body?.error?.message || body?.message || `HTTP ${res.status}`;
+          // Detect specific error types for clearer messages
+          const lcMsg = rawMsg.toLowerCase();
+          let errMsg = rawMsg;
+          let hint = '';
+          if (lcMsg.includes('credit') || lcMsg.includes('balance') || lcMsg.includes('quota') || lcMsg.includes('billing') || lcMsg.includes('exceeded') || lcMsg.includes('insufficient')) {
+            errMsg = 'no credits';
+            if (p.name === 'Anthropic') hint = `\n       ${c.dim}└─ Add credits: console.anthropic.com/settings/plans${c.reset}`;
+            else if (p.name === 'OpenAI') hint = `\n       ${c.dim}└─ Check usage: platform.openai.com/usage${c.reset}`;
+            else if (p.name === 'OpenRouter') hint = `\n       ${c.dim}└─ Check balance: openrouter.ai/credits${c.reset}`;
+          } else if (res.status === 401 || lcMsg.includes('invalid') || lcMsg.includes('unauthorized') || lcMsg.includes('authentication')) {
+            errMsg = 'invalid key';
+            if (p.name === 'Anthropic') hint = `\n       ${c.dim}└─ Check key: console.anthropic.com/settings/keys${c.reset}`;
+            else if (p.name === 'OpenAI') hint = `\n       ${c.dim}└─ Check key: platform.openai.com/api-keys${c.reset}`;
+          } else if (res.status === 429) {
+            errMsg = 'rate limited';
+            hint = `\n       ${c.dim}└─ Try again in a moment${c.reset}`;
+          }
+          process.stdout.write(`\r    ${c.red}●${c.reset}  ${p.name.padEnd(12)} ${c.dim}${masked}${c.reset}  ${c.red}✖ ${errMsg}${c.reset}${hint}  \n`);
         }
       } catch (e) {
         process.stdout.write(`\r    ${c.red}●${c.reset}  ${p.name.padEnd(12)} ${c.dim}${masked}${c.reset}  ${c.red}error ✗${c.reset} ${c.dim}(${e.message})${c.reset}  \n`);
@@ -1781,10 +1858,13 @@ async function main() {
     const resolved = resolveProvider(null, keys);
     console.log();
     if (resolved) {
-      console.log(`    ${c.bold}Active provider:${c.reset} ${resolved.label}`);
-      console.log(`    ${c.dim}Override with: --provider=openai | --provider=openrouter | --provider=anthropic${c.reset}`);
+      console.log(`    ${c.bold}Active:${c.reset} ${c.green}${resolved.label}${c.reset}`);
+      console.log(`    ${c.dim}Override: --provider=<name> or AGENTAUDIT_PROVIDER=<name>${c.reset}`);
+      console.log(`    ${c.dim}Set default: agentaudit config set provider <name>${c.reset}`);
     } else {
-      console.log(`    ${c.yellow}No LLM provider configured.${c.reset} Set one of the API keys above for deep audits.`);
+      console.log(`    ${c.yellow}⚠  No working LLM provider.${c.reset} Deep audits require one.`);
+      console.log(`    ${c.dim}Set a key: export ANTHROPIC_API_KEY=sk-ant-...${c.reset}`);
+      console.log(`    ${c.dim}Or scan without LLM: agentaudit scan <url>${c.reset}`);
     }
 
     // AgentAudit registry key
@@ -1808,10 +1888,47 @@ async function main() {
     return;
   }
   
+  if (command === 'config') {
+    const subCmd = targets[0];
+    if (subCmd === 'set' && targets[1] === 'provider' && targets[2]) {
+      const validProviders = ['anthropic', 'openai', 'openrouter', 'ollama', 'custom', 'claude', 'gpt'];
+      const val = targets[2].toLowerCase();
+      if (!validProviders.includes(val)) {
+        console.log(`  ${c.red}✖  Unknown provider: ${val}${c.reset}`);
+        console.log(`     ${c.dim}Valid: anthropic, openai, openrouter, ollama, custom${c.reset}`);
+        process.exitCode = 2; return;
+      }
+      saveConfig({ preferred_provider: val });
+      console.log(`  ${c.green}✔${c.reset}  Default provider set to: ${c.bold}${val}${c.reset}`);
+      console.log(`     ${c.dim}Override per-command: --provider=<name>${c.reset}`);
+      console.log(`     ${c.dim}Or env: AGENTAUDIT_PROVIDER=<name>${c.reset}`);
+    } else if (subCmd === 'get' || !subCmd) {
+      const cfg = loadConfig();
+      console.log(`  ${c.bold}Config:${c.reset} ${USER_CONFIG_FILE}`);
+      if (Object.keys(cfg).length === 0) {
+        console.log(`  ${c.dim}(empty — using defaults)${c.reset}`);
+      } else {
+        for (const [k, v] of Object.entries(cfg)) {
+          console.log(`  ${c.dim}${k}:${c.reset} ${v}`);
+        }
+      }
+    } else if (subCmd === 'reset') {
+      try { fs.unlinkSync(USER_CONFIG_FILE); } catch {}
+      console.log(`  ${c.green}✔${c.reset}  Config reset to defaults.`);
+    } else {
+      console.log(`  ${c.red}✖  Unknown config command${c.reset}`);
+      console.log(`     ${c.dim}Usage: agentaudit config set provider <name>${c.reset}`);
+      console.log(`     ${c.dim}       agentaudit config get${c.reset}`);
+      console.log(`     ${c.dim}       agentaudit config reset${c.reset}`);
+    }
+    return;
+  }
+  
   if (command === 'lookup' || command === 'check') {
     const names = targets.filter(t => !t.startsWith('--'));
     if (names.length === 0) {
-      console.log(`  ${c.red}Error: package name required${c.reset}`);
+      console.log(`  ${c.red}✖  Package name or URL required${c.reset}`);
+      console.log(`     ${c.dim}Usage: agentaudit check <name|url>${c.reset}`);
       process.exitCode = 2;
       return;
     }
@@ -1824,31 +1941,18 @@ async function main() {
       console.log(JSON.stringify(results.length === 1 ? (results[0] || { error: 'not_found' }) : results, null, 2));
     }
     process.exitCode = 0; return;
-    return;
   }
   
   if (command === 'scan') {
-    const deepFlag = targets.includes('--deep');
     const urls = targets.filter(t => !t.startsWith('--'));
     if (urls.length === 0) {
-      console.log(`  ${c.red}Error: at least one repository URL required${c.reset}`);
-      console.log(`  ${c.dim}Tip: use ${c.cyan}agentaudit discover${c.dim} to find & check locally installed MCP servers${c.reset}`);
-      console.log(`  ${c.dim}Tip: use ${c.cyan}agentaudit audit <url>${c.dim} for a deep LLM-powered audit${c.reset}`);
+      console.log(`  ${c.red}✖  Repository URL required${c.reset}`);
+      console.log(`     ${c.dim}Usage: agentaudit scan <url>${c.reset}`);
+      console.log(`     ${c.dim}Or discover local servers: ${c.cyan}agentaudit discover${c.reset}`);
       process.exitCode = 2;
       return;
     }
     
-    // --deep redirects to audit flow
-    if (deepFlag) {
-      let hasFindings = false;
-      for (const url of urls) {
-        const report = await auditRepo(url);
-        if (report?.findings?.length > 0) hasFindings = true;
-      }
-      process.exitCode = hasFindings ? 1 : 0;
-      return;
-    }
-    
     const results = [];
     let hadErrors = false;
     for (const url of urls) {
@@ -1885,7 +1989,8 @@ async function main() {
   if (command === 'audit') {
     const urls = targets.filter(t => !t.startsWith('--'));
     if (urls.length === 0) {
-      console.log(`  ${c.red}Error: at least one repository URL required${c.reset}`);
+      console.log(`  ${c.red}✖  Repository URL required${c.reset}`);
+      console.log(`     ${c.dim}Usage: agentaudit audit <url>${c.reset}`);
       process.exitCode = 2;
       return;
     }
@@ -1899,8 +2004,18 @@ async function main() {
     return;
   }
   
-  console.log(`  ${c.red}Unknown command: ${command}${c.reset}`);
-  console.log(`  ${c.dim}Run agentaudit --help for usage${c.reset}`);
+  // Typo correction via Levenshtein distance
+  const knownCommands = ['discover', 'scan', 'audit', 'check', 'lookup', 'status', 'setup', 'config'];
+  const suggestion = knownCommands
+    .map(cmd => ({ cmd, dist: levenshtein(command, cmd) }))
+    .filter(x => x.dist <= 3)
+    .sort((a, b) => a.dist - b.dist)[0];
+  
+  console.log(`  ${c.red}✖  Unknown command: ${command}${c.reset}`);
+  if (suggestion) {
+    console.log(`     ${c.dim}Did you mean: ${c.cyan}agentaudit ${suggestion.cmd}${c.reset}${c.dim}?${c.reset}`);
+  }
+  console.log(`     ${c.dim}Run ${c.cyan}agentaudit --help${c.dim} for usage${c.reset}`);
   process.exitCode = 2;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentaudit",
-  "version": "3.9.18",
+  "version": "3.9.20",
   "description": "Security scanner for AI packages — MCP server + CLI",
   "type": "module",
   "bin": {