agentaudit 3.10.0 → 3.10.2

package/cli.mjs

@@ -1,16 +1,20 @@
 #!/usr/bin/env node
 /**
  * AgentAudit CLI — Security scanner for AI packages
- * 
- * 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 setup                                Register + configure API key
- * 
- * Global flags: --json, --quiet, --no-color
+ *
+ * Usage: agentaudit <command> [options]
+ *
+ * Commands:
+ *   discover              Find MCP servers in AI editors
+ *   scan <url> [url...]   Quick static scan (regex)
+ *   audit <url> [url...]  Deep LLM-powered security audit
+ *   lookup <name>         Look up package in registry
+ *   model [name|reset]    Configure LLM provider + model
+ *   setup                 Create account / enter API key
+ *   status                Show current config + auth status
+ *   help [command]        Show help
+ *
+ * Flags: --json, --quiet, --no-color, --no-upload, --model, --export, --debug
  */
 
 import fs from 'fs';
@@ -49,6 +53,51 @@ const LLM_PROVIDERS = [
   { key: 'OPENROUTER_API_KEY',  name: 'OpenRouter',            provider: 'openrouter',  type: 'openai',    model: 'anthropic/claude-sonnet-4', url: 'https://openrouter.ai/api/v1/chat/completions' },
 ];
 
+// ── Provider-specific model choices (for interactive menu) ──
+const PROVIDER_MODELS = {
+  anthropic: [
+    { label: 'claude-sonnet-4-20250514', sublabel: 'fast + smart (default)', value: 'claude-sonnet-4-20250514' },
+    { label: 'claude-opus-4-20250514',   sublabel: 'most capable',           value: 'claude-opus-4-20250514' },
+  ],
+  openai: [
+    { label: 'gpt-4o',  sublabel: 'fast multimodal (default)', value: 'gpt-4o' },
+    { label: 'gpt-4.1', sublabel: 'latest',                    value: 'gpt-4.1' },
+  ],
+  google: [
+    { label: 'gemini-2.5-flash', sublabel: 'fast + cheap (default)', value: 'gemini-2.5-flash' },
+    { label: 'gemini-2.5-pro',   sublabel: 'most capable',          value: 'gemini-2.5-pro' },
+  ],
+  deepseek: [
+    { label: 'deepseek-chat', sublabel: 'cost-effective (default)', value: 'deepseek-chat' },
+  ],
+  mistral: [
+    { label: 'mistral-large-latest', sublabel: 'EU-hosted (default)', value: 'mistral-large-latest' },
+  ],
+  groq: [
+    { label: 'llama-3.3-70b-versatile', sublabel: 'ultra-fast (default)', value: 'llama-3.3-70b-versatile' },
+  ],
+  xai: [
+    { label: 'grok-3', sublabel: 'real-time knowledge (default)', value: 'grok-3' },
+  ],
+  together: [
+    { label: 'meta-llama/Llama-3.3-70B-Instruct-Turbo', sublabel: 'open source (default)', value: 'meta-llama/Llama-3.3-70B-Instruct-Turbo' },
+  ],
+  fireworks: [
+    { label: 'accounts/fireworks/models/llama-v3p3-70b-instruct', sublabel: 'open source (default)', value: 'accounts/fireworks/models/llama-v3p3-70b-instruct' },
+  ],
+  cerebras: [
+    { label: 'llama-3.3-70b', sublabel: 'fast inference (default)', value: 'llama-3.3-70b' },
+  ],
+  zhipu: [
+    { label: 'glm-4.7', sublabel: 'Chinese language (default)', value: 'glm-4.7' },
+  ],
+  openrouter: [
+    { label: 'anthropic/claude-sonnet-4', sublabel: 'default',         value: 'anthropic/claude-sonnet-4' },
+    { label: 'qwen/qwen3-coder',          sublabel: 'code specialist', value: 'qwen/qwen3-coder' },
+    { label: 'meta-llama/Llama-3.3-70B',  sublabel: 'open source',    value: 'meta-llama/Llama-3.3-70B' },
+  ],
+};
+
 // ── ANSI Colors (respects NO_COLOR and --no-color) ───────
 
 const noColor = !!(process.env.NO_COLOR || process.argv.includes('--no-color'));
@@ -114,20 +163,23 @@ function loadLlmConfig() {
     if (fs.existsSync(f)) {
       try {
         const data = JSON.parse(fs.readFileSync(f, 'utf8'));
-        if (data.llm_model) return { llm_model: data.llm_model };
+        if (data.llm_model || data.preferred_provider) {
+          return { llm_model: data.llm_model || null, preferred_provider: data.preferred_provider || null };
+        }
       } catch {}
     }
   }
   return null;
 }
 
-function saveLlmConfig(model) {
+function saveLlmConfig(model, provider) {
   // Merge into existing credentials
   let existing = {};
   if (fs.existsSync(USER_CRED_FILE)) {
     try { existing = JSON.parse(fs.readFileSync(USER_CRED_FILE, 'utf8')); } catch {}
   }
-  existing.llm_model = model;
+  if (model !== undefined) existing.llm_model = model;
+  if (provider !== undefined) existing.preferred_provider = provider;
   const json = JSON.stringify(existing, null, 2);
   fs.mkdirSync(USER_CRED_DIR, { recursive: true });
   fs.writeFileSync(USER_CRED_FILE, json, { mode: 0o600 });
@@ -136,12 +188,32 @@ function saveLlmConfig(model) {
     if (fs.existsSync(SKILL_CRED_FILE)) {
       try { skillExisting = JSON.parse(fs.readFileSync(SKILL_CRED_FILE, 'utf8')); } catch {}
     }
-    skillExisting.llm_model = model;
+    if (model !== undefined) skillExisting.llm_model = model;
+    if (provider !== undefined) skillExisting.preferred_provider = provider;
     fs.mkdirSync(path.dirname(SKILL_CRED_FILE), { recursive: true });
     fs.writeFileSync(SKILL_CRED_FILE, JSON.stringify(skillExisting, null, 2), { mode: 0o600 });
   } catch {}
 }
 
+function resolveProvider() {
+  const config = loadLlmConfig();
+  const preferred = config?.preferred_provider;
+
+  if (preferred) {
+    // Find provider by name, check if any of their keys is set
+    const match = LLM_PROVIDERS.find(p => p.provider === preferred && process.env[p.key]);
+    if (match) return match;
+    // Key missing for preferred provider — warn + fallback
+    const providerInfo = LLM_PROVIDERS.find(p => p.provider === preferred);
+    if (providerInfo && !quietMode) {
+      console.log(`  ${c.yellow}Preferred provider "${providerInfo.name}" missing key (${providerInfo.key}), falling back...${c.reset}`);
+    }
+  }
+
+  // Fallback: first match wins
+  return LLM_PROVIDERS.find(p => process.env[p.key]) || null;
+}
+
 function saveCredentials(data) {
   const json = JSON.stringify(data, null, 2);
   fs.mkdirSync(USER_CRED_DIR, { recursive: true });
@@ -398,31 +470,17 @@ async function setupCommand() {
 
   console.log();
 
-  // ── LLM model configuration ──
+  // ── LLM configuration hint ──
   const llmConfig = loadLlmConfig();
-  console.log(`  ${c.bold}LLM Model Configuration${c.reset}`);
-  console.log(`  ${c.dim}Used for deep audits. Requires an LLM API key in your environment.${c.reset}`);
-  console.log();
-  if (llmConfig) {
-    console.log(`  ${icons.safe}  Current model: ${c.bold}${llmConfig.llm_model}${c.reset}`);
-    console.log();
-  }
-  console.log(`  ${c.dim}Examples:${c.reset}`);
-  console.log(`    ${c.dim}claude-sonnet-4-20250514${c.reset}        ${c.dim}(Anthropic)${c.reset}`);
-  console.log(`    ${c.dim}gpt-4o${c.reset}                          ${c.dim}(OpenAI)${c.reset}`);
-  console.log(`    ${c.dim}gemini-2.5-flash${c.reset}                ${c.dim}(Google)${c.reset}`);
-  console.log(`    ${c.dim}qwen/qwen3.5-coder-32b${c.reset}         ${c.dim}(OpenRouter)${c.reset}`);
-  console.log(`    ${c.dim}deepseek-chat${c.reset}                   ${c.dim}(DeepSeek)${c.reset}`);
-  console.log();
-  const modelAnswer = await askQuestion(`  Model ${c.dim}(Enter to keep default, or type model name)${c.reset}: `);
-  if (modelAnswer) {
-    saveLlmConfig(modelAnswer);
-    console.log(`  ${icons.safe}  Model set to ${c.bold}${modelAnswer}${c.reset}`);
-  } else if (llmConfig) {
-    console.log(`  ${c.dim}Keeping: ${llmConfig.llm_model}${c.reset}`);
-  } else {
-    console.log(`  ${c.dim}No custom model — will use provider default${c.reset}`);
-  }
+  console.log(`  ${c.bold}LLM Configuration${c.reset}`);
+  if (llmConfig?.llm_model || llmConfig?.preferred_provider) {
+    const parts = [];
+    if (llmConfig.preferred_provider) parts.push(llmConfig.preferred_provider);
+    if (llmConfig.llm_model) parts.push(llmConfig.llm_model);
+    console.log(`  ${icons.safe}  Current: ${c.bold}${parts.join(' → ')}${c.reset}`);
+  }
+  console.log(`  ${c.dim}Run ${c.cyan}agentaudit model${c.dim} to configure your LLM provider and model.${c.reset}`);
+  console.log(`  ${c.dim}Deep audits require an LLM API key in your environment.${c.reset}`);
   console.log();
 
   console.log(`  ${c.bold}Ready!${c.reset} You can now:`);
@@ -1513,8 +1571,8 @@ async function auditRepo(url) {
   console.log(` ${c.green}done${c.reset}`);
   
   // Step 4: LLM Analysis
-  // Detect provider from environment variables (first match wins)
-  const activeLlm = LLM_PROVIDERS.find(p => process.env[p.key]);
+  // Resolve provider: preferred_provider from config → first match fallback
+  const activeLlm = resolveProvider();
   const llmApiKey = activeLlm ? process.env[activeLlm.key] : null;
   const activeProvider = activeLlm ? activeLlm.name : null;
 
@@ -1529,34 +1587,16 @@ async function auditRepo(url) {
   }
   
   if (!activeLlm) {
-    // No LLM API key — clear explanation
+    // No LLM API key — compact 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();
-    console.log(`  ${c.bold}Option 1: Set an API key${c.reset} (any one of these):`);
-    console.log(`  ${c.cyan}ANTHROPIC_API_KEY${c.reset}    Anthropic Claude`);
-    console.log(`  ${c.cyan}OPENAI_API_KEY${c.reset}       OpenAI GPT-4o`);
-    console.log(`  ${c.cyan}GEMINI_API_KEY${c.reset}       Google Gemini`);
-    console.log(`  ${c.cyan}DEEPSEEK_API_KEY${c.reset}     DeepSeek`);
-    console.log(`  ${c.cyan}MISTRAL_API_KEY${c.reset}      Mistral`);
-    console.log(`  ${c.cyan}XAI_API_KEY${c.reset}          xAI Grok`);
-    console.log(`  ${c.cyan}GROQ_API_KEY${c.reset}         Groq`);
-    console.log(`  ${c.cyan}TOGETHER_API_KEY${c.reset}     Together AI`);
-    console.log(`  ${c.cyan}FIREWORKS_API_KEY${c.reset}    Fireworks AI`);
-    console.log(`  ${c.cyan}CEREBRAS_API_KEY${c.reset}     Cerebras`);
-    console.log(`  ${c.cyan}ZAI_API_KEY${c.reset}          Zhipu AI (GLM)`);
-    console.log(`  ${c.cyan}OPENROUTER_API_KEY${c.reset}   OpenRouter (any model)`);
-    console.log();
-    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.bold}Set an API key${c.reset} (e.g. ${c.cyan}export OPENROUTER_API_KEY=sk-or-...${c.reset})`);
+    console.log(`  ${c.dim}Run "agentaudit model" to configure provider + model interactively${c.reset}`);
     console.log();
-    console.log(`  ${c.bold}Option 2: Export for manual review${c.reset}`);
-    console.log(`  ${c.cyan}agentaudit audit ${url} --export${c.reset}`);
-    console.log(`  ${c.dim}Creates a markdown file you can paste into any LLM${c.reset}`);
-    console.log();
-    console.log(`  ${c.bold}Option 3: Use MCP in Claude/Cursor/Windsurf (no API key needed)${c.reset}`);
-    console.log(`  ${c.dim}Add AgentAudit as MCP server — your editor's agent runs the audit using its own LLM.${c.reset}`);
-    console.log(`  ${c.dim}Config: { "mcpServers": { "agentaudit": { "command": "npx", "args": ["-y", "agentaudit"] } } }${c.reset}`);
+    console.log(`  ${c.bold}Or export for manual review:${c.reset} ${c.cyan}agentaudit audit ${url} --export${c.reset}`);
+    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}{ "agentaudit": { "command": "npx", "args": ["-y", "agentaudit"] } }${c.reset}`);
     console.log();
     
     // Check if --export flag
@@ -1793,9 +1833,12 @@ async function auditRepo(url) {
     console.log();
   }
   
-  // Upload to registry
-  const creds = loadCredentials();
-  if (creds) {
+  // Upload to registry (skip with --no-upload)
+  const noUpload = process.argv.includes('--no-upload');
+  let creds = loadCredentials();
+  if (noUpload) {
+    // Skip silently
+  } else if (creds) {
     process.stdout.write(`  Uploading report to registry...`);
     try {
       const res = await fetch(`${REGISTRY_URL}/api/reports`, {
@@ -1817,8 +1860,51 @@ async function auditRepo(url) {
     } catch (err) {
       console.log(` ${c.yellow}failed${c.reset}`);
     }
+  } else if (process.stdin.isTTY) {
+    // No credentials — offer inline registration
+    console.log();
+    console.log(`  ${c.bold}Share this audit with the community?${c.reset}`);
+    console.log(`  ${c.dim}Uploading helps others assess package security. Account is free.${c.reset}`);
+    console.log();
+    console.log(`  ${c.bold}1)${c.reset} Create account + upload ${c.dim}(free)${c.reset}`);
+    console.log(`  ${c.bold}2)${c.reset} Skip`);
+    console.log();
+    const uploadChoice = await askQuestion(`  Choice ${c.dim}(1/2)${c.reset}: `);
+    if (uploadChoice === '1') {
+      const name = await askQuestion(`  Agent name ${c.dim}(e.g. my-scanner, claude-desktop)${c.reset}: `);
+      if (!name || !/^[a-zA-Z0-9._-]{2,64}$/.test(name)) {
+        console.log(`  ${c.red}Invalid name. Use 2-64 chars: letters, numbers, dash, underscore, dot.${c.reset}`);
+      } else {
+        try {
+          process.stdout.write(`  Registering ${c.bold}${name}${c.reset}...`);
+          const regData = await registerAgent(name);
+          saveCredentials({ api_key: regData.api_key, agent_name: regData.agent_name });
+          console.log(` ${c.green}done!${c.reset}`);
+          creds = { api_key: regData.api_key, agent_name: regData.agent_name };
+          process.stdout.write(`  Uploading report...`);
+          const res = await fetch(`${REGISTRY_URL}/api/reports`, {
+            method: 'POST',
+            headers: {
+              'Authorization': `Bearer ${creds.api_key}`,
+              'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(report),
+            signal: AbortSignal.timeout(15_000),
+          });
+          if (res.ok) {
+            console.log(` ${c.green}done${c.reset}`);
+            console.log(`  ${c.dim}Report: ${REGISTRY_URL}/skills/${slug}${c.reset}`);
+          } else {
+            console.log(` ${c.yellow}failed (HTTP ${res.status})${c.reset}`);
+          }
+        } catch (err) {
+          console.log(` ${c.red}failed${c.reset}`);
+          console.log(`  ${c.dim}${err.message}${c.reset}`);
+        }
+      }
+    }
   } else {
-    console.log(`  ${c.dim}Run ${c.cyan}agentaudit setup${c.dim} to upload reports to the registry${c.reset}`);
+    console.log(`  ${c.dim}Run ${c.cyan}agentaudit setup${c.dim} to create an account and upload reports${c.reset}`);
   }
   
   console.log();
@@ -1871,60 +1957,196 @@ async function main() {
   // --no-color already handled at top level for `c` object
   
   // Strip global flags from args (including --model <value>)
-  const globalFlags = new Set(['--json', '--quiet', '-q', '--no-color']);
+  const globalFlags = new Set(['--json', '--quiet', '-q', '--no-color', '--no-upload']);
   let args = rawArgs.filter(a => !globalFlags.has(a));
   // Remove --model <value> pair
   const modelIdx = args.indexOf('--model');
   if (modelIdx !== -1) args.splice(modelIdx, 2);
   
+  // Detect per-command --help BEFORE stripping (e.g. `agentaudit model --help`)
+  const wantsHelp = args.includes('--help') || args.includes('-h');
+  // Strip --help/-h from args for routing
+  args = args.filter(a => a !== '--help' && a !== '-h');
+
   if (args[0] === '-v' || args[0] === '--version') {
     console.log(`agentaudit ${getVersion()}`);
     process.exitCode = 0; return;
   }
-  
-  if (args[0] === '--help' || args[0] === '-h') {
+
+  // Subcommand help definitions
+  const subcommandHelp = {
+    discover: [
+      `${c.bold}agentaudit discover${c.reset} [options]`,
+      ``,
+      `Find MCP servers configured in your AI editors (Cursor, Claude Desktop, VS Code, Windsurf).`,
+      ``,
+      `${c.bold}Options:${c.reset}`,
+      `  --quick, -s    Auto-scan all discovered servers (regex-based)`,
+      `  --deep, -a     Interactively select servers for deep LLM audit`,
+      ``,
+      `${c.bold}Examples:${c.reset}`,
+      `  agentaudit discover`,
+      `  agentaudit discover --quick`,
+      `  agentaudit discover --deep`,
+    ],
+    scan: [
+      `${c.bold}agentaudit scan${c.reset} <url> [url...] [options]`,
+      ``,
+      `Quick regex-based static security scan (~2s). Checks for 15+ patterns`,
+      `(command injection, eval, hardcoded secrets, path traversal, etc.)`,
+      ``,
+      `${c.bold}Options:${c.reset}`,
+      `  --deep         Run deep LLM audit instead (same as \`agentaudit audit\`)`,
+      ``,
+      `${c.bold}Examples:${c.reset}`,
+      `  agentaudit scan https://github.com/owner/repo`,
+      `  agentaudit scan https://github.com/a/b https://github.com/c/d`,
+      `  agentaudit scan https://github.com/owner/repo --deep`,
+    ],
+    audit: [
+      `${c.bold}agentaudit audit${c.reset} <url> [url...] [options]`,
+      ``,
+      `Deep LLM-powered 3-pass security audit (~30s). Requires an LLM API key.`,
+      ``,
+      `${c.bold}Options:${c.reset}`,
+      `  --model <name>   Override LLM model for this run`,
+      `  --no-upload      Skip uploading report to registry`,
+      `  --export         Export audit payload as markdown (for manual LLM review)`,
+      `  --debug          Show raw LLM response on parse errors`,
+      ``,
+      `${c.bold}Examples:${c.reset}`,
+      `  agentaudit audit https://github.com/owner/repo`,
+      `  agentaudit audit https://github.com/owner/repo --no-upload`,
+      `  agentaudit audit https://github.com/owner/repo --model gpt-4o`,
+      `  agentaudit audit https://github.com/owner/repo --export`,
+    ],
+    lookup: [
+      `${c.bold}agentaudit lookup${c.reset} <name> [options]`,
+      ``,
+      `Look up a package in the AgentAudit registry. Shows trust score,`,
+      `findings, confidence level, and audit history.`,
+      ``,
+      `${c.bold}Aliases:${c.reset} lookup, check`,
+      ``,
+      `${c.bold}Examples:${c.reset}`,
+      `  agentaudit lookup fastmcp`,
+      `  agentaudit lookup @anthropic/mcp-server-filesystem --json`,
+      `  agentaudit check fastmcp`,
+    ],
+    check: null, // alias → lookup
+    model: [
+      `${c.bold}agentaudit model${c.reset} [name|reset]`,
+      ``,
+      `Configure LLM provider and model. Interactive two-step menu when`,
+      `called without arguments: choose provider, then choose model.`,
+      ``,
+      `${c.bold}Usage:${c.reset}`,
+      `  agentaudit model              Interactive provider + model menu`,
+      `  agentaudit model <name>       Set model directly (keeps current provider)`,
+      `  agentaudit model reset        Reset provider + model to defaults`,
+      ``,
+      `${c.bold}Examples:${c.reset}`,
+      `  agentaudit model`,
+      `  agentaudit model gpt-4o`,
+      `  agentaudit model qwen/qwen3-coder`,
+      `  agentaudit model reset`,
+    ],
+    setup: [
+      `${c.bold}agentaudit setup${c.reset}`,
+      ``,
+      `Create an AgentAudit account or enter an existing API key.`,
+      `This is for uploading audit reports to the registry — not for`,
+      `LLM provider configuration (use \`agentaudit model\` for that).`,
+      ``,
+      `${c.bold}Examples:${c.reset}`,
+      `  agentaudit setup`,
+    ],
+    status: [
+      `${c.bold}agentaudit status${c.reset}`,
+      ``,
+      `Show current configuration: active LLM provider, model, account`,
+      `status, and which API keys are available.`,
+      ``,
+      `${c.bold}Aliases:${c.reset} status, whoami`,
+      ``,
+      `${c.bold}Examples:${c.reset}`,
+      `  agentaudit status`,
+      `  agentaudit status --json`,
+    ],
+  };
+
+  // Show subcommand help: `agentaudit help <cmd>` or `agentaudit <cmd> --help`
+  function showSubcommandHelp(cmd) {
+    let helpLines = subcommandHelp[cmd];
+    if (helpLines === null && subcommandHelp[cmd] === null) {
+      // alias redirect
+      const alias = cmd === 'check' ? 'lookup' : cmd;
+      helpLines = subcommandHelp[alias];
+    }
+    if (!helpLines) {
+      console.log(`  ${c.red}No help available for "${cmd}"${c.reset}`);
+      console.log(`  ${c.dim}Run ${c.cyan}agentaudit help${c.dim} for available commands${c.reset}`);
+      return;
+    }
     banner();
-    console.log(`  ${c.bold}Commands:${c.reset}`);
+    for (const line of helpLines) console.log(`  ${line}`);
     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 model${c.reset} [name|reset]               View or set default LLM model`);
-    console.log(`    ${c.cyan}agentaudit setup${c.reset}                             Register + configure API key`);
+  }
+
+  // Handle: `agentaudit <cmd> --help` (wantsHelp + has a command)
+  if (wantsHelp && args[0] && args[0] !== '--help' && args[0] !== '-h') {
+    const cmd = args[0];
+    if (subcommandHelp[cmd] !== undefined) {
+      showSubcommandHelp(cmd);
+      process.exitCode = 0; return;
+    }
+  }
+
+  // Handle: `agentaudit help [cmd]`
+  if (args[0] === 'help') {
+    const helpCmd = args[1];
+    if (helpCmd && subcommandHelp[helpCmd] !== undefined) {
+      showSubcommandHelp(helpCmd);
+      process.exitCode = 0; return;
+    }
+    // No subcommand or unknown → show main help
+    wantsHelp || (args[0] = '--help'); // fall through to main help
+  }
+
+  if (args[0] === '--help' || args[0] === '-h' || args[0] === 'help' || (wantsHelp && args.length === 0)) {
+    banner();
+    console.log(`  ${c.bold}USAGE${c.reset}`);
+    console.log(`    agentaudit <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}--model <name>   Override LLM model (e.g. qwen/qwen3.5-coder-32b)${c.reset}`);
+    console.log(`  ${c.bold}SCAN & AUDIT${c.reset}`);
+    console.log(`    ${c.cyan}discover${c.reset}              Find MCP servers in your AI editors`);
+    console.log(`    ${c.cyan}scan${c.reset} <url> [url...]   Quick static scan (regex, ~2s)`);
+    console.log(`    ${c.cyan}audit${c.reset} <url> [url...]  Deep LLM-powered security audit (~30s)`);
+    console.log(`    ${c.cyan}lookup${c.reset} <name>         Look up package in registry`);
     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}CONFIGURATION${c.reset}`);
+    console.log(`    ${c.cyan}model${c.reset}                 Configure LLM provider + model`);
+    console.log(`    ${c.cyan}setup${c.reset}                 Create account / enter API key`);
+    console.log(`    ${c.cyan}status${c.reset}                Show current config + auth status`);
     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}FLAGS${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 ANSI colors (also: NO_COLOR env)${c.reset}`);
+    console.log(`    ${c.dim}--model <name>     Override LLM model for this run${c.reset}`);
+    console.log(`    ${c.dim}--no-upload        Skip uploading report to registry${c.reset}`);
+    console.log(`    ${c.dim}--export           Export audit payload as markdown${c.reset}`);
+    console.log(`    ${c.dim}--debug            Show raw LLM response on parse errors${c.reset}`);
     console.log();
-    console.log(`  ${c.bold}Examples:${c.reset}`);
-    console.log(`    agentaudit`);
+    console.log(`  ${c.bold}EXAMPLES${c.reset}`);
     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();
-    console.log(`  ${c.bold}For deep audits,${c.reset} set any LLM API key:`);
-    console.log(`    ${c.dim}ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, DEEPSEEK_API_KEY,${c.reset}`);
-    console.log(`    ${c.dim}MISTRAL_API_KEY, XAI_API_KEY, GROQ_API_KEY, TOGETHER_API_KEY,${c.reset}`);
-    console.log(`    ${c.dim}FIREWORKS_API_KEY, CEREBRAS_API_KEY, ZAI_API_KEY, or OPENROUTER_API_KEY${c.reset}`);
-    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}LEARN MORE${c.reset}`);
+    console.log(`    ${c.dim}agentaudit help <command>${c.reset}     Help for a specific command`);
+    console.log(`    ${c.dim}https://agentaudit.dev${c.reset}        Documentation`);
     console.log();
     process.exitCode = 0; return;
   }
@@ -1940,25 +2162,98 @@ async function main() {
     return;
   }
 
+  if (command === 'status' || command === 'whoami') {
+    // ── Status / diagnostic overview ──
+    const config = loadLlmConfig();
+    const creds = loadCredentials();
+    const resolved = resolveProvider();
+
+    console.log(`  ${c.bold}Status${c.reset}`);
+    console.log();
+
+    // Provider + Model
+    const prefProvider = config?.preferred_provider;
+    const prefModel = config?.llm_model;
+    if (prefProvider && resolved) {
+      console.log(`  Provider    ${c.bold}${resolved.name}${c.reset}  ${c.dim}(${resolved.key})${c.reset}  ${c.green}✔${c.reset}`);
+    } else if (resolved) {
+      console.log(`  Provider    ${c.bold}${resolved.name}${c.reset}  ${c.dim}(auto-detected via ${resolved.key})${c.reset}  ${c.green}✔${c.reset}`);
+    } else {
+      console.log(`  Provider    ${c.yellow}none${c.reset}  ${c.dim}— set an API key or run ${c.cyan}agentaudit model${c.dim}${c.reset}`);
+    }
+
+    if (prefModel) {
+      console.log(`  Model       ${c.bold}${prefModel}${c.reset}  ${c.dim}(custom)${c.reset}`);
+    } else if (resolved) {
+      console.log(`  Model       ${c.dim}${resolved.model} (provider default)${c.reset}`);
+    } else {
+      console.log(`  Model       ${c.dim}—${c.reset}`);
+    }
+    console.log();
+
+    // Account / auth
+    if (creds) {
+      console.log(`  Account     ${c.bold}${creds.agent_name}${c.reset}  ${c.green}✔ logged in${c.reset}`);
+      console.log(`  ${c.dim}            Key: ${creds.api_key.slice(0, 12)}...${c.reset}`);
+    } else {
+      console.log(`  Account     ${c.yellow}not configured${c.reset}  ${c.dim}— run ${c.cyan}agentaudit setup${c.dim} to create one${c.reset}`);
+    }
+    console.log();
+
+    // All provider keys
+    const seen = new Set();
+    const keyLines = [];
+    for (const p of LLM_PROVIDERS) {
+      if (seen.has(p.provider)) continue;
+      seen.add(p.provider);
+      const keys = LLM_PROVIDERS.filter(x => x.provider === p.provider);
+      const hasKey = keys.some(x => process.env[x.key]);
+      keyLines.push({ name: p.name, key: p.key, hasKey });
+    }
+    console.log(`  ${c.bold}API Keys${c.reset}`);
+    for (const k of keyLines) {
+      const icon = k.hasKey ? `${c.green}✔${c.reset}` : `${c.dim}✗${c.reset}`;
+      const label = k.hasKey ? k.name : `${c.dim}${k.name}${c.reset}`;
+      console.log(`    ${icon}  ${label}  ${c.dim}${k.key}${c.reset}`);
+    }
+    console.log();
+
+    // JSON mode
+    if (jsonMode) {
+      const status = {
+        version: getVersion(),
+        provider: resolved ? { name: resolved.name, provider: resolved.provider, key: resolved.key, model: prefModel || resolved.model } : null,
+        account: creds ? { agent_name: creds.agent_name, has_key: true } : null,
+        api_keys: keyLines.reduce((acc, k) => { acc[k.key] = k.hasKey; return acc; }, {}),
+      };
+      console.log(JSON.stringify(status, null, 2));
+    }
+    return;
+  }
+
   if (command === 'model') {
     const newModel = targets.filter(t => !t.startsWith('--'))[0];
-    const current = loadLlmConfig()?.llm_model;
+    const config = loadLlmConfig();
+    const current = config?.llm_model;
+    const currentProvider = config?.preferred_provider;
 
-    // Direct set: agentaudit model <name>
+    // Direct set: agentaudit model reset
     if (newModel === 'reset' || newModel === 'clear') {
       for (const f of [USER_CRED_FILE, SKILL_CRED_FILE]) {
         if (fs.existsSync(f)) {
           try {
             const data = JSON.parse(fs.readFileSync(f, 'utf8'));
             delete data.llm_model;
+            delete data.preferred_provider;
             fs.writeFileSync(f, JSON.stringify(data, null, 2), { mode: 0o600 });
           } catch {}
         }
       }
-      console.log(`  ${icons.safe}  Model reset to provider default`);
+      console.log(`  ${icons.safe}  Model + provider reset to defaults`);
       return;
     }
 
+    // Direct set: agentaudit model <name> (sets model only, keeps provider)
     if (newModel) {
       saveLlmConfig(newModel);
       console.log(`  ${icons.safe}  Model set to ${c.bold}${newModel}${c.reset}`);
@@ -1966,82 +2261,136 @@ async function main() {
       return;
     }
 
-    // No argument — interactive menu
-    const activeLlm = LLM_PROVIDERS.find(p => process.env[p.key]);
-    console.log(`  ${c.bold}LLM Model Configuration${c.reset}`);
+    // ── No argument — interactive two-step menu ──
+
+    // Build deduplicated provider list
+    const seen = new Set();
+    const providerList = [];
+    for (const p of LLM_PROVIDERS) {
+      if (seen.has(p.provider)) continue;
+      seen.add(p.provider);
+      // Check if ANY key for this provider is set
+      const keys = LLM_PROVIDERS.filter(x => x.provider === p.provider);
+      const hasKey = keys.some(x => process.env[x.key]);
+      const keyName = p.key;
+      providerList.push({
+        label: p.name,
+        sublabel: hasKey
+          ? `${keyName} ${c.green}✔${c.reset}`
+          : `${keyName} ${c.red}✗${c.reset}  ${c.dim}set: export ${keyName}=...${c.reset}`,
+        value: p.provider,
+        hasKey,
+        keyName,
+      });
+    }
+
+    // Show status
+    const resolved = resolveProvider();
+    console.log(`  ${c.bold}LLM Configuration${c.reset}`);
     console.log();
-    if (current) {
-      console.log(`  Current: ${c.bold}${c.cyan}${current}${c.reset}`);
+    if (currentProvider && current) {
+      const provInfo = LLM_PROVIDERS.find(p => p.provider === currentProvider);
+      console.log(`  Active:  ${c.bold}${c.cyan}${provInfo?.name || currentProvider} → ${current}${c.reset}`);
+    } else if (current) {
+      console.log(`  Active:  ${c.bold}${c.cyan}${resolved?.name || 'auto'} → ${current}${c.reset}`);
+    } else if (resolved) {
+      console.log(`  Active:  ${c.dim}${resolved.name} → ${resolved.model} (defaults)${c.reset}`);
     } else {
-      console.log(`  Current: ${c.dim}(provider default${activeLlm ? `: ${activeLlm.model}` : ''})${c.reset}`);
-    }
-    if (activeLlm) {
-      console.log(`  Provider: ${c.dim}${activeLlm.name} (${activeLlm.key})${c.reset}`);
+      console.log(`  Active:  ${c.yellow}no provider configured${c.reset}`);
     }
     console.log();
 
-    // Build menu items — deduplicate providers, show popular models
+    // Step A: Provider selection
+    const providerChoices = [
+      ...providerList,
+      { label: '(keep current)', sublabel: '', value: '__keep__', hasKey: true },
+    ];
+
+    const selectedProvider = await singleSelect(providerChoices, {
+      title: 'Choose provider',
+      hint: '↑↓ move  Enter select  Esc cancel',
+    });
+
+    if (selectedProvider === null) {
+      console.log(`  ${c.dim}Cancelled${c.reset}`);
+      return;
+    }
+
+    if (selectedProvider === '__keep__') {
+      console.log(`  ${c.dim}Keeping current config${c.reset}`);
+      return;
+    }
+
+    // Check if provider has key set
+    const chosenEntry = providerList.find(p => p.value === selectedProvider);
+    if (chosenEntry && !chosenEntry.hasKey) {
+      console.log();
+      console.log(`  ${c.yellow}${chosenEntry.keyName} is not set.${c.reset}`);
+      console.log(`  ${c.dim}Run: export ${chosenEntry.keyName}=your-key-here${c.reset}`);
+      console.log(`  ${c.dim}Then run "agentaudit model" again.${c.reset}`);
+      return;
+    }
+
+    // Step B: Model selection for chosen provider
+    console.log();
+    const providerModels = PROVIDER_MODELS[selectedProvider] || [];
     const modelChoices = [
-      { label: 'claude-sonnet-4-20250514',                      sublabel: 'Anthropic — fast + smart',         value: 'claude-sonnet-4-20250514' },
-      { label: 'claude-opus-4-20250514',                        sublabel: 'Anthropic — most capable',         value: 'claude-opus-4-20250514' },
-      { label: 'gpt-4o',                                        sublabel: 'OpenAI — fast multimodal',         value: 'gpt-4o' },
-      { label: 'gpt-4.1',                                       sublabel: 'OpenAI — latest',                  value: 'gpt-4.1' },
-      { label: 'gemini-2.5-flash',                               sublabel: 'Google — fast + cheap',            value: 'gemini-2.5-flash' },
-      { label: 'gemini-2.5-pro',                                 sublabel: 'Google — most capable',            value: 'gemini-2.5-pro' },
-      { label: 'deepseek-chat',                                  sublabel: 'DeepSeek — cost-effective',        value: 'deepseek-chat' },
-      { label: 'qwen/qwen3-coder',                              sublabel: 'OpenRouter — code specialist',     value: 'qwen/qwen3-coder' },
-      { label: 'mistral-large-latest',                           sublabel: 'Mistral — EU-hosted',              value: 'mistral-large-latest' },
-      { label: 'grok-3',                                         sublabel: 'xAI — real-time knowledge',        value: 'grok-3' },
-      { label: 'meta-llama/Llama-3.3-70B-Instruct-Turbo',      sublabel: 'Together AI — open source',        value: 'meta-llama/Llama-3.3-70B-Instruct-Turbo' },
-      { label: 'llama-3.3-70b-versatile',                        sublabel: 'Groq — ultra-fast inference',      value: 'llama-3.3-70b-versatile' },
-      { label: '(reset to provider default)',                     sublabel: '',                                 value: '__reset__' },
-      { label: '(enter custom model name)',                       sublabel: '',                                 value: '__custom__' },
+      ...providerModels,
+      { label: '(enter custom model name)', sublabel: '', value: '__custom__' },
+      { label: '(reset to provider default)', sublabel: '', value: '__reset__' },
     ];
 
-    const selected = await singleSelect(modelChoices, {
-      title: 'Choose default model',
-      hint: '↑↓=move  Enter=select  Esc=cancel',
+    const providerName = LLM_PROVIDERS.find(p => p.provider === selectedProvider)?.name || selectedProvider;
+    const selectedModel = await singleSelect(modelChoices, {
+      title: `Choose model for ${providerName}`,
+      hint: '↑↓ move  Enter select  Esc cancel',
     });
 
-    if (selected === null) {
+    if (selectedModel === null) {
       console.log(`  ${c.dim}Cancelled${c.reset}`);
       return;
     }
 
-    if (selected === '__reset__') {
+    if (selectedModel === '__reset__') {
+      // Save provider, clear model (use provider default)
+      saveLlmConfig(undefined, selectedProvider);
+      // Also clear llm_model from both files
       for (const f of [USER_CRED_FILE, SKILL_CRED_FILE]) {
         if (fs.existsSync(f)) {
           try {
             const data = JSON.parse(fs.readFileSync(f, 'utf8'));
             delete data.llm_model;
+            data.preferred_provider = selectedProvider;
             fs.writeFileSync(f, JSON.stringify(data, null, 2), { mode: 0o600 });
           } catch {}
         }
       }
+      const defaultModel = LLM_PROVIDERS.find(p => p.provider === selectedProvider)?.model;
       console.log();
-      console.log(`  ${icons.safe}  Model reset to provider default`);
+      console.log(`  ${icons.safe}  Provider: ${c.bold}${providerName}${c.reset}, model: ${c.dim}${defaultModel} (default)${c.reset}`);
       return;
     }
 
-    if (selected === '__custom__') {
+    if (selectedModel === '__custom__') {
       console.log();
       const custom = await askQuestion(`  Model name: `);
       if (!custom) {
         console.log(`  ${c.dim}Cancelled${c.reset}`);
         return;
       }
-      saveLlmConfig(custom);
-      console.log(`  ${icons.safe}  Model set to ${c.bold}${custom}${c.reset}`);
-      if (current) console.log(`  ${c.dim}Was: ${current}${c.reset}`);
+      saveLlmConfig(custom, selectedProvider);
+      console.log(`  ${icons.safe}  Provider: ${c.bold}${providerName}${c.reset}, model: ${c.bold}${custom}${c.reset}`);
+      if (current) console.log(`  ${c.dim}Was: ${currentProvider || 'auto'} → ${current}${c.reset}`);
       return;
     }
 
-    saveLlmConfig(selected);
+    // Normal model selection
+    saveLlmConfig(selectedModel, selectedProvider);
     console.log();
-    console.log(`  ${icons.safe}  Model set to ${c.bold}${selected}${c.reset}`);
-    if (current) console.log(`  ${c.dim}Was: ${current}${c.reset}`);
+    console.log(`  ${icons.safe}  Provider: ${c.bold}${providerName}${c.reset}, model: ${c.bold}${selectedModel}${c.reset}`);
+    if (current) console.log(`  ${c.dim}Was: ${currentProvider || 'auto'} → ${current}${c.reset}`);
     console.log();
-    console.log(`  ${c.dim}Tip: agentaudit model <name>  to set directly, or  agentaudit model reset${c.reset}`);
+    console.log(`  ${c.dim}Tip: agentaudit model <name>  to set model directly, or  agentaudit model reset${c.reset}`);
     return;
   }
   
@@ -2056,6 +2405,7 @@ async function main() {
     const names = targets.filter(t => !t.startsWith('--'));
     if (names.length === 0) {
       console.log(`  ${c.red}Error: package name required${c.reset}`);
+      console.log(`  ${c.dim}Usage: ${c.cyan}agentaudit lookup <name>${c.dim} — e.g. agentaudit lookup fastmcp${c.reset}`);
       process.exitCode = 2;
       return;
     }
@@ -2068,7 +2418,6 @@ 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') {
@@ -2130,6 +2479,8 @@ async function main() {
     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}Usage: ${c.cyan}agentaudit audit <url>${c.dim} — e.g. agentaudit audit https://github.com/owner/repo${c.reset}`);
+      console.log(`  ${c.dim}Tip: use ${c.cyan}agentaudit discover --deep${c.dim} to find & audit locally installed MCP servers${c.reset}`);
       process.exitCode = 2;
       return;
     }
@@ -2144,7 +2495,7 @@ async function main() {
   }
   
   console.log(`  ${c.red}Unknown command: ${command}${c.reset}`);
-  console.log(`  ${c.dim}Run agentaudit --help for usage${c.reset}`);
+  console.log(`  ${c.dim}Run ${c.cyan}agentaudit help${c.dim} for available commands${c.reset}`);
   process.exitCode = 2;
 }
 

package/package.json

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