agentaudit 3.10.1 → 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, --no-upload
+ *
+ * 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';
@@ -1959,53 +1963,190 @@ async function main() {
   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}                             Configure LLM provider + model interactively`);
-    console.log(`    ${c.cyan}agentaudit model${c.reset} <name>                     Set model directly (e.g. gpt-4o)`);
-    console.log(`    ${c.cyan}agentaudit setup${c.reset}                             Create account / enter API key (for report uploads)`);
+  }
+
+  // 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 for this run${c.reset}`);
-    console.log(`    ${c.dim}--no-upload      Skip uploading report to registry${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 an LLM API key (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}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(`  ${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;
   }
@@ -2021,6 +2162,75 @@ 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 config = loadLlmConfig();
@@ -2195,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;
     }
@@ -2207,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') {
@@ -2269,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;
     }
@@ -2283,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.1",
+  "version": "3.10.2",
   "description": "Security scanner for AI packages — MCP server + CLI",
   "type": "module",
   "bin": {