@optave/codegraph 2.5.1 → 3.0.0

package/src/cli.js

@@ -3,6 +3,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { Command } from 'commander';
+import { audit } from './audit.js';
+import { BATCH_COMMANDS, batch, multiBatchData, splitTargets } from './batch.js';
 import { buildGraph } from './builder.js';
 import { loadConfig } from './config.js';
 import { findCycles, formatCycles } from './cycles.js';
@@ -14,19 +16,28 @@ import {
   MODELS,
   search,
 } from './embedder.js';
-import { exportDOT, exportJSON, exportMermaid } from './export.js';
+import {
+  exportDOT,
+  exportGraphML,
+  exportGraphSON,
+  exportJSON,
+  exportMermaid,
+  exportNeo4jCSV,
+} from './export.js';
 import { setVerbose } from './logger.js';
+import { printNdjson } from './paginate.js';
 import {
-  ALL_SYMBOL_KINDS,
+  children,
   context,
   diffImpact,
+  EVERY_SYMBOL_KIND,
   explain,
   fileDeps,
+  fileExports,
   fnDeps,
   fnImpact,
   impactAnalysis,
   moduleMap,
-  queryName,
   roles,
   stats,
   symbolPath,
@@ -40,6 +51,7 @@ import {
   registerRepo,
   unregisterRepo,
 } from './registry.js';
+import { snapshotDelete, snapshotList, snapshotRestore, snapshotSave } from './snapshot.js';
 import { checkForUpdates, printUpdateNotification } from './update-check.js';
 import { watchProject } from './watcher.js';
 
@@ -83,20 +95,41 @@ function resolveNoTests(opts) {
   return config.query?.excludeTests || false;
 }
 
+function formatSize(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
 program
   .command('build [dir]')
   .description('Parse repo and build graph in .codegraph/graph.db')
   .option('--no-incremental', 'Force full rebuild (ignore file hashes)')
+  .option('--dataflow', 'Extract data flow edges (flows_to, returns, mutates)')
+  .option('--cfg', 'Build intraprocedural control flow graphs')
   .action(async (dir, opts) => {
     const root = path.resolve(dir || '.');
     const engine = program.opts().engine;
-    await buildGraph(root, { incremental: opts.incremental, engine });
+    await buildGraph(root, {
+      incremental: opts.incremental,
+      engine,
+      dataflow: opts.dataflow,
+      cfg: opts.cfg,
+    });
   });
 
 program
   .command('query <name>')
-  .description('Find a function/class, show callers and callees')
+  .description('Function-level dependency chain or shortest path between symbols')
   .option('-d, --db <path>', 'Path to graph.db')
+  .option('--depth <n>', 'Transitive caller depth', '3')
+  .option('-f, --file <path>', 'Scope search to functions in this file (partial match)')
+  .option('-k, --kind <kind>', 'Filter to a specific symbol kind')
+  .option('--path <to>', 'Path mode: find shortest path to <to>')
+  .option('--kinds <kinds>', 'Path mode: comma-separated edge kinds to follow (default: calls)')
+  .option('--reverse', 'Path mode: follow edges backward')
+  .option('--from-file <path>', 'Path mode: disambiguate source symbol by file')
+  .option('--to-file <path>', 'Path mode: disambiguate target symbol by file')
   .option('-T, --no-tests', 'Exclude test/spec files from results')
   .option('--include-tests', 'Include test/spec files (overrides excludeTests config)')
   .option('-j, --json', 'Output as JSON')
@@ -104,12 +137,63 @@ program
   .option('--offset <number>', 'Skip N results (default: 0)')
   .option('--ndjson', 'Newline-delimited JSON output')
   .action((name, opts) => {
-    queryName(name, opts.db, {
+    if (opts.kind && !EVERY_SYMBOL_KIND.includes(opts.kind)) {
+      console.error(`Invalid kind "${opts.kind}". Valid: ${EVERY_SYMBOL_KIND.join(', ')}`);
+      process.exit(1);
+    }
+    if (opts.path) {
+      console.error('Note: "query --path" is deprecated, use "codegraph path <from> <to>" instead');
+      symbolPath(name, opts.path, opts.db, {
+        maxDepth: opts.depth ? parseInt(opts.depth, 10) : 10,
+        edgeKinds: opts.kinds ? opts.kinds.split(',').map((s) => s.trim()) : undefined,
+        reverse: opts.reverse,
+        fromFile: opts.fromFile,
+        toFile: opts.toFile,
+        kind: opts.kind,
+        noTests: resolveNoTests(opts),
+        json: opts.json,
+      });
+    } else {
+      fnDeps(name, opts.db, {
+        depth: parseInt(opts.depth, 10),
+        file: opts.file,
+        kind: opts.kind,
+        noTests: resolveNoTests(opts),
+        json: opts.json,
+        limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
+        offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
+        ndjson: opts.ndjson,
+      });
+    }
+  });
+
+program
+  .command('path <from> <to>')
+  .description('Find shortest path between two symbols')
+  .option('-d, --db <path>', 'Path to graph.db')
+  .option('--reverse', 'Follow edges backward')
+  .option('--kinds <kinds>', 'Comma-separated edge kinds to follow (default: calls)')
+  .option('--from-file <path>', 'Disambiguate source symbol by file')
+  .option('--to-file <path>', 'Disambiguate target symbol by file')
+  .option('--depth <n>', 'Max traversal depth', '10')
+  .option('-k, --kind <kind>', 'Filter to a specific symbol kind')
+  .option('-T, --no-tests', 'Exclude test/spec files from results')
+  .option('--include-tests', 'Include test/spec files (overrides excludeTests config)')
+  .option('-j, --json', 'Output as JSON')
+  .action((from, to, opts) => {
+    if (opts.kind && !EVERY_SYMBOL_KIND.includes(opts.kind)) {
+      console.error(`Invalid kind "${opts.kind}". Valid: ${EVERY_SYMBOL_KIND.join(', ')}`);
+      process.exit(1);
+    }
+    symbolPath(from, to, opts.db, {
+      maxDepth: opts.depth ? parseInt(opts.depth, 10) : 10,
+      edgeKinds: opts.kinds ? opts.kinds.split(',').map((s) => s.trim()) : undefined,
+      reverse: opts.reverse,
+      fromFile: opts.fromFile,
+      toFile: opts.toFile,
+      kind: opts.kind,
       noTests: resolveNoTests(opts),
       json: opts.json,
-      limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
-      offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
-      ndjson: opts.ndjson,
     });
   });
 
@@ -120,8 +204,17 @@ program
   .option('-T, --no-tests', 'Exclude test/spec files from results')
   .option('--include-tests', 'Include test/spec files (overrides excludeTests config)')
   .option('-j, --json', 'Output as JSON')
+  .option('--limit <number>', 'Max results to return')
+  .option('--offset <number>', 'Skip N results (default: 0)')
+  .option('--ndjson', 'Newline-delimited JSON output')
   .action((file, opts) => {
-    impactAnalysis(file, opts.db, { noTests: resolveNoTests(opts), json: opts.json });
+    impactAnalysis(file, opts.db, {
+      noTests: resolveNoTests(opts),
+      json: opts.json,
+      limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
+      offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
+      ndjson: opts.ndjson,
+    });
   });
 
 program
@@ -157,31 +250,36 @@ program
   .option('-T, --no-tests', 'Exclude test/spec files from results')
   .option('--include-tests', 'Include test/spec files (overrides excludeTests config)')
   .option('-j, --json', 'Output as JSON')
+  .option('--limit <number>', 'Max results to return')
+  .option('--offset <number>', 'Skip N results (default: 0)')
+  .option('--ndjson', 'Newline-delimited JSON output')
   .action((file, opts) => {
-    fileDeps(file, opts.db, { noTests: resolveNoTests(opts), json: opts.json });
+    fileDeps(file, opts.db, {
+      noTests: resolveNoTests(opts),
+      json: opts.json,
+      limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
+      offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
+      ndjson: opts.ndjson,
+    });
   });
 
 program
-  .command('fn <name>')
-  .description('Function-level dependencies: callers, callees, and transitive call chain')
+  .command('exports <file>')
+  .description('Show exported symbols with per-symbol consumers (who calls each export)')
   .option('-d, --db <path>', 'Path to graph.db')
-  .option('--depth <n>', 'Transitive caller depth', '3')
-  .option('-f, --file <path>', 'Scope search to functions in this file (partial match)')
-  .option('-k, --kind <kind>', 'Filter to a specific symbol kind')
   .option('-T, --no-tests', 'Exclude test/spec files from results')
   .option('--include-tests', 'Include test/spec files (overrides excludeTests config)')
   .option('-j, --json', 'Output as JSON')
-  .action((name, opts) => {
-    if (opts.kind && !ALL_SYMBOL_KINDS.includes(opts.kind)) {
-      console.error(`Invalid kind "${opts.kind}". Valid: ${ALL_SYMBOL_KINDS.join(', ')}`);
-      process.exit(1);
-    }
-    fnDeps(name, opts.db, {
-      depth: parseInt(opts.depth, 10),
-      file: opts.file,
-      kind: opts.kind,
+  .option('--limit <number>', 'Max results to return')
+  .option('--offset <number>', 'Skip N results (default: 0)')
+  .option('--ndjson', 'Newline-delimited JSON output')
+  .action((file, opts) => {
+    fileExports(file, opts.db, {
       noTests: resolveNoTests(opts),
       json: opts.json,
+      limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
+      offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
+      ndjson: opts.ndjson,
     });
   });
 
@@ -195,9 +293,12 @@ program
   .option('-T, --no-tests', 'Exclude test/spec files from results')
   .option('--include-tests', 'Include test/spec files (overrides excludeTests config)')
   .option('-j, --json', 'Output as JSON')
+  .option('--limit <number>', 'Max results to return')
+  .option('--offset <number>', 'Skip N results (default: 0)')
+  .option('--ndjson', 'Newline-delimited JSON output')
   .action((name, opts) => {
-    if (opts.kind && !ALL_SYMBOL_KINDS.includes(opts.kind)) {
-      console.error(`Invalid kind "${opts.kind}". Valid: ${ALL_SYMBOL_KINDS.join(', ')}`);
+    if (opts.kind && !EVERY_SYMBOL_KIND.includes(opts.kind)) {
+      console.error(`Invalid kind "${opts.kind}". Valid: ${EVERY_SYMBOL_KIND.join(', ')}`);
       process.exit(1);
     }
     fnImpact(name, opts.db, {
@@ -206,78 +307,105 @@ program
       kind: opts.kind,
       noTests: resolveNoTests(opts),
       json: opts.json,
+      limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
+      offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
+      ndjson: opts.ndjson,
     });
   });
 
 program
-  .command('path <from> <to>')
-  .description('Find shortest path between two symbols (A calls...calls B)')
+  .command('context <name>')
+  .description('Full context for a function: source, deps, callers, tests, signature')
   .option('-d, --db <path>', 'Path to graph.db')
-  .option('--max-depth <n>', 'Maximum BFS depth', '10')
-  .option('--kinds <kinds>', 'Comma-separated edge kinds to follow (default: calls)')
-  .option('--reverse', 'Follow edges backward (B is called by...called by A)')
-  .option('--from-file <path>', 'Disambiguate source symbol by file (partial match)')
-  .option('--to-file <path>', 'Disambiguate target symbol by file (partial match)')
-  .option('-k, --kind <kind>', 'Filter both symbols by kind')
+  .option('--depth <n>', 'Include callee source up to N levels deep', '0')
+  .option('-f, --file <path>', 'Scope search to functions in this file (partial match)')
+  .option('-k, --kind <kind>', 'Filter to a specific symbol kind')
+  .option('--no-source', 'Metadata only (skip source extraction)')
+  .option('--with-test-source', 'Include test source code')
   .option('-T, --no-tests', 'Exclude test/spec files from results')
   .option('--include-tests', 'Include test/spec files (overrides excludeTests config)')
   .option('-j, --json', 'Output as JSON')
-  .action((from, to, opts) => {
-    if (opts.kind && !ALL_SYMBOL_KINDS.includes(opts.kind)) {
-      console.error(`Invalid kind "${opts.kind}". Valid: ${ALL_SYMBOL_KINDS.join(', ')}`);
+  .option('--limit <number>', 'Max results to return')
+  .option('--offset <number>', 'Skip N results (default: 0)')
+  .option('--ndjson', 'Newline-delimited JSON output')
+  .action((name, opts) => {
+    if (opts.kind && !EVERY_SYMBOL_KIND.includes(opts.kind)) {
+      console.error(`Invalid kind "${opts.kind}". Valid: ${EVERY_SYMBOL_KIND.join(', ')}`);
       process.exit(1);
     }
-    symbolPath(from, to, opts.db, {
-      maxDepth: parseInt(opts.maxDepth, 10),
-      edgeKinds: opts.kinds ? opts.kinds.split(',').map((s) => s.trim()) : undefined,
-      reverse: opts.reverse,
-      fromFile: opts.fromFile,
-      toFile: opts.toFile,
+    context(name, opts.db, {
+      depth: parseInt(opts.depth, 10),
+      file: opts.file,
       kind: opts.kind,
+      noSource: !opts.source,
       noTests: resolveNoTests(opts),
+      includeTests: opts.withTestSource,
       json: opts.json,
+      limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
+      offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
+      ndjson: opts.ndjson,
     });
   });
 
 program
-  .command('context <name>')
-  .description('Full context for a function: source, deps, callers, tests, signature')
+  .command('children <name>')
+  .description('List parameters, properties, and constants of a symbol')
   .option('-d, --db <path>', 'Path to graph.db')
-  .option('--depth <n>', 'Include callee source up to N levels deep', '0')
-  .option('-f, --file <path>', 'Scope search to functions in this file (partial match)')
+  .option('-f, --file <path>', 'Scope search to symbols in this file (partial match)')
   .option('-k, --kind <kind>', 'Filter to a specific symbol kind')
-  .option('--no-source', 'Metadata only (skip source extraction)')
-  .option('--with-test-source', 'Include test source code')
   .option('-T, --no-tests', 'Exclude test/spec files from results')
-  .option('--include-tests', 'Include test/spec files (overrides excludeTests config)')
   .option('-j, --json', 'Output as JSON')
+  .option('--limit <number>', 'Max results to return')
+  .option('--offset <number>', 'Skip N results (default: 0)')
   .action((name, opts) => {
-    if (opts.kind && !ALL_SYMBOL_KINDS.includes(opts.kind)) {
-      console.error(`Invalid kind "${opts.kind}". Valid: ${ALL_SYMBOL_KINDS.join(', ')}`);
+    if (opts.kind && !EVERY_SYMBOL_KIND.includes(opts.kind)) {
+      console.error(`Invalid kind "${opts.kind}". Valid: ${EVERY_SYMBOL_KIND.join(', ')}`);
       process.exit(1);
     }
-    context(name, opts.db, {
-      depth: parseInt(opts.depth, 10),
+    children(name, opts.db, {
       file: opts.file,
       kind: opts.kind,
-      noSource: !opts.source,
       noTests: resolveNoTests(opts),
-      includeTests: opts.withTestSource,
       json: opts.json,
+      limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
+      offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
     });
   });
 
 program
-  .command('explain <target>')
-  .description('Structural summary of a file or function (no LLM needed)')
+  .command('audit <target>')
+  .description('Composite report: explain + impact + health metrics per function')
   .option('-d, --db <path>', 'Path to graph.db')
-  .option('--depth <n>', 'Recursively explain dependencies up to N levels deep', '0')
+  .option('--quick', 'Structural summary only (skip impact analysis and health metrics)')
+  .option('--depth <n>', 'Impact/explain depth', '3')
+  .option('-f, --file <path>', 'Scope to file (partial match)')
+  .option('-k, --kind <kind>', 'Filter by symbol kind')
   .option('-T, --no-tests', 'Exclude test/spec files from results')
   .option('--include-tests', 'Include test/spec files (overrides excludeTests config)')
   .option('-j, --json', 'Output as JSON')
+  .option('--limit <number>', 'Max results to return (quick mode)')
+  .option('--offset <number>', 'Skip N results (quick mode)')
+  .option('--ndjson', 'Newline-delimited JSON output (quick mode)')
   .action((target, opts) => {
-    explain(target, opts.db, {
+    if (opts.kind && !EVERY_SYMBOL_KIND.includes(opts.kind)) {
+      console.error(`Invalid kind "${opts.kind}". Valid: ${EVERY_SYMBOL_KIND.join(', ')}`);
+      process.exit(1);
+    }
+    if (opts.quick) {
+      explain(target, opts.db, {
+        depth: parseInt(opts.depth, 10),
+        noTests: resolveNoTests(opts),
+        json: opts.json,
+        limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
+        offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
+        ndjson: opts.ndjson,
+      });
+      return;
+    }
+    audit(target, opts.db, {
       depth: parseInt(opts.depth, 10),
+      file: opts.file,
+      kind: opts.kind,
       noTests: resolveNoTests(opts),
       json: opts.json,
     });
@@ -320,6 +448,9 @@ program
   .option('--include-tests', 'Include test/spec files (overrides excludeTests config)')
   .option('-j, --json', 'Output as JSON')
   .option('-f, --format <format>', 'Output format: text, mermaid, json', 'text')
+  .option('--limit <number>', 'Max results to return')
+  .option('--offset <number>', 'Skip N results (default: 0)')
+  .option('--ndjson', 'Newline-delimited JSON output')
   .action((ref, opts) => {
     diffImpact(opts.db, {
       ref,
@@ -328,16 +459,99 @@ program
       noTests: resolveNoTests(opts),
       json: opts.json,
       format: opts.format,
+      limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
+      offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
+      ndjson: opts.ndjson,
+    });
+  });
+
+program
+  .command('check [ref]')
+  .description(
+    'CI gate: run manifesto rules (no args), diff predicates (with ref/--staged), or both (--rules)',
+  )
+  .option('-d, --db <path>', 'Path to graph.db')
+  .option('--staged', 'Analyze staged changes')
+  .option('--rules', 'Also run manifesto rules alongside diff predicates')
+  .option('--cycles', 'Assert no dependency cycles involve changed files')
+  .option('--blast-radius <n>', 'Assert no function exceeds N transitive callers')
+  .option('--signatures', 'Assert no function declaration lines were modified')
+  .option('--boundaries', 'Assert no cross-owner boundary violations')
+  .option('--depth <n>', 'Max BFS depth for blast radius (default: 3)')
+  .option('-f, --file <path>', 'Scope to file (partial match, manifesto mode)')
+  .option('-k, --kind <kind>', 'Filter by symbol kind (manifesto mode)')
+  .option('-T, --no-tests', 'Exclude test/spec files from results')
+  .option('--include-tests', 'Include test/spec files (overrides excludeTests config)')
+  .option('-j, --json', 'Output as JSON')
+  .option('--limit <number>', 'Max results to return (manifesto mode)')
+  .option('--offset <number>', 'Skip N results (manifesto mode)')
+  .option('--ndjson', 'Newline-delimited JSON output (manifesto mode)')
+  .action(async (ref, opts) => {
+    const isDiffMode = ref || opts.staged;
+
+    if (!isDiffMode && !opts.rules) {
+      // No ref, no --staged → run manifesto rules on whole codebase
+      if (opts.kind && !EVERY_SYMBOL_KIND.includes(opts.kind)) {
+        console.error(`Invalid kind "${opts.kind}". Valid: ${EVERY_SYMBOL_KIND.join(', ')}`);
+        process.exit(1);
+      }
+      const { manifesto } = await import('./manifesto.js');
+      manifesto(opts.db, {
+        file: opts.file,
+        kind: opts.kind,
+        noTests: resolveNoTests(opts),
+        json: opts.json,
+        limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
+        offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
+        ndjson: opts.ndjson,
+      });
+      return;
+    }
+
+    // Diff predicates mode
+    const { check } = await import('./check.js');
+    check(opts.db, {
+      ref,
+      staged: opts.staged,
+      cycles: opts.cycles || undefined,
+      blastRadius: opts.blastRadius ? parseInt(opts.blastRadius, 10) : undefined,
+      signatures: opts.signatures || undefined,
+      boundaries: opts.boundaries || undefined,
+      depth: opts.depth ? parseInt(opts.depth, 10) : undefined,
+      noTests: resolveNoTests(opts),
+      json: opts.json,
     });
+
+    // If --rules, also run manifesto after diff predicates
+    if (opts.rules) {
+      if (opts.kind && !EVERY_SYMBOL_KIND.includes(opts.kind)) {
+        console.error(`Invalid kind "${opts.kind}". Valid: ${EVERY_SYMBOL_KIND.join(', ')}`);
+        process.exit(1);
+      }
+      const { manifesto } = await import('./manifesto.js');
+      manifesto(opts.db, {
+        file: opts.file,
+        kind: opts.kind,
+        noTests: resolveNoTests(opts),
+        json: opts.json,
+        limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
+        offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
+        ndjson: opts.ndjson,
+      });
+    }
   });
 
 // ─── New commands ────────────────────────────────────────────────────────
 
 program
   .command('export')
-  .description('Export dependency graph as DOT (Graphviz), Mermaid, or JSON')
+  .description('Export dependency graph as DOT, Mermaid, JSON, GraphML, GraphSON, or Neo4j CSV')
   .option('-d, --db <path>', 'Path to graph.db')
-  .option('-f, --format <format>', 'Output format: dot, mermaid, json', 'dot')
+  .option(
+    '-f, --format <format>',
+    'Output format: dot, mermaid, json, graphml, graphson, neo4j',
+    'dot',
+  )
   .option('--functions', 'Function-level graph instead of file-level')
   .option('-T, --no-tests', 'Exclude test/spec files')
   .option('--include-tests', 'Include test/spec files (overrides excludeTests config)')
@@ -361,6 +575,25 @@ program
       case 'json':
         output = JSON.stringify(exportJSON(db, exportOpts), null, 2);
         break;
+      case 'graphml':
+        output = exportGraphML(db, exportOpts);
+        break;
+      case 'graphson':
+        output = JSON.stringify(exportGraphSON(db, exportOpts), null, 2);
+        break;
+      case 'neo4j': {
+        const csv = exportNeo4jCSV(db, exportOpts);
+        if (opts.output) {
+          const base = opts.output.replace(/\.[^.]+$/, '') || opts.output;
+          fs.writeFileSync(`${base}-nodes.csv`, csv.nodes, 'utf-8');
+          fs.writeFileSync(`${base}-relationships.csv`, csv.relationships, 'utf-8');
+          db.close();
+          console.log(`Exported to ${base}-nodes.csv and ${base}-relationships.csv`);
+          return;
+        }
+        output = `--- nodes.csv ---\n${csv.nodes}\n\n--- relationships.csv ---\n${csv.relationships}`;
+        break;
+      }
       default:
         output = exportDOT(db, exportOpts);
         break;
@@ -376,6 +609,81 @@ program
     }
   });
 
+program
+  .command('plot')
+  .description('Generate an interactive HTML dependency graph viewer')
+  .option('-d, --db <path>', 'Path to graph.db')
+  .option('--functions', 'Function-level graph instead of file-level')
+  .option('-T, --no-tests', 'Exclude test/spec files')
+  .option('--include-tests', 'Include test/spec files (overrides excludeTests config)')
+  .option('--min-confidence <score>', 'Minimum edge confidence threshold (default: 0.5)', '0.5')
+  .option('-o, --output <file>', 'Write HTML to file')
+  .option('-c, --config <path>', 'Path to .plotDotCfg config file')
+  .option('--no-open', 'Do not open in browser')
+  .option('--cluster <mode>', 'Cluster nodes: none | community | directory')
+  .option('--overlay <list>', 'Comma-separated overlays: complexity,risk')
+  .option('--seed <strategy>', 'Seed strategy: all | top-fanin | entry')
+  .option('--seed-count <n>', 'Number of seed nodes (default: 30)')
+  .option('--size-by <metric>', 'Size nodes by: uniform | fan-in | fan-out | complexity')
+  .option('--color-by <mode>', 'Color nodes by: kind | role | community | complexity')
+  .action(async (opts) => {
+    const { generatePlotHTML, loadPlotConfig } = await import('./viewer.js');
+    const os = await import('node:os');
+    const db = openReadonlyOrFail(opts.db);
+
+    let plotCfg;
+    if (opts.config) {
+      try {
+        plotCfg = JSON.parse(fs.readFileSync(opts.config, 'utf-8'));
+      } catch (e) {
+        console.error(`Failed to load config: ${e.message}`);
+        db.close();
+        process.exitCode = 1;
+        return;
+      }
+    } else {
+      plotCfg = loadPlotConfig(process.cwd());
+    }
+
+    // Merge CLI flags into config
+    if (opts.cluster) plotCfg.clusterBy = opts.cluster;
+    if (opts.colorBy) plotCfg.colorBy = opts.colorBy;
+    if (opts.sizeBy) plotCfg.sizeBy = opts.sizeBy;
+    if (opts.seed) plotCfg.seedStrategy = opts.seed;
+    if (opts.seedCount) plotCfg.seedCount = parseInt(opts.seedCount, 10);
+    if (opts.overlay) {
+      const parts = opts.overlay.split(',').map((s) => s.trim());
+      if (!plotCfg.overlays) plotCfg.overlays = {};
+      if (parts.includes('complexity')) plotCfg.overlays.complexity = true;
+      if (parts.includes('risk')) plotCfg.overlays.risk = true;
+    }
+
+    const html = generatePlotHTML(db, {
+      fileLevel: !opts.functions,
+      noTests: resolveNoTests(opts),
+      minConfidence: parseFloat(opts.minConfidence),
+      config: plotCfg,
+    });
+    db.close();
+
+    const outPath = opts.output || path.join(os.tmpdir(), `codegraph-plot-${Date.now()}.html`);
+    fs.writeFileSync(outPath, html, 'utf-8');
+    console.log(`Plot written to ${outPath}`);
+
+    if (opts.open !== false) {
+      const { execFile } = await import('node:child_process');
+      const args =
+        process.platform === 'win32'
+          ? ['cmd', ['/c', 'start', '', outPath]]
+          : process.platform === 'darwin'
+            ? ['open', [outPath]]
+            : ['xdg-open', [outPath]];
+      execFile(args[0], args[1], (err) => {
+        if (err) console.error('Could not open browser:', err.message);
+      });
+    }
+  });
+
 program
   .command('cycles')
   .description('Detect circular dependencies in the codebase')
@@ -498,6 +806,81 @@ registry
     }
   });
 
+// ─── Snapshot commands ──────────────────────────────────────────────────
+
+const snapshot = program
+  .command('snapshot')
+  .description('Save and restore graph database snapshots');
+
+snapshot
+  .command('save <name>')
+  .description('Save a snapshot of the current graph database')
+  .option('-d, --db <path>', 'Path to graph.db')
+  .option('--force', 'Overwrite existing snapshot')
+  .action((name, opts) => {
+    try {
+      const result = snapshotSave(name, { dbPath: opts.db, force: opts.force });
+      console.log(`Snapshot saved: ${result.name} (${formatSize(result.size)})`);
+    } catch (err) {
+      console.error(err.message);
+      process.exit(1);
+    }
+  });
+
+snapshot
+  .command('restore <name>')
+  .description('Restore a snapshot over the current graph database')
+  .option('-d, --db <path>', 'Path to graph.db')
+  .action((name, opts) => {
+    try {
+      snapshotRestore(name, { dbPath: opts.db });
+      console.log(`Snapshot "${name}" restored.`);
+    } catch (err) {
+      console.error(err.message);
+      process.exit(1);
+    }
+  });
+
+snapshot
+  .command('list')
+  .description('List all saved snapshots')
+  .option('-d, --db <path>', 'Path to graph.db')
+  .option('-j, --json', 'Output as JSON')
+  .action((opts) => {
+    try {
+      const snapshots = snapshotList({ dbPath: opts.db });
+      if (opts.json) {
+        console.log(JSON.stringify(snapshots, null, 2));
+      } else if (snapshots.length === 0) {
+        console.log('No snapshots found.');
+      } else {
+        console.log(`Snapshots (${snapshots.length}):\n`);
+        for (const s of snapshots) {
+          console.log(
+            `  ${s.name.padEnd(30)} ${formatSize(s.size).padStart(10)}  ${s.createdAt.toISOString()}`,
+          );
+        }
+      }
+    } catch (err) {
+      console.error(err.message);
+      process.exit(1);
+    }
+  });
+
+snapshot
+  .command('delete <name>')
+  .description('Delete a saved snapshot')
+  .option('-d, --db <path>', 'Path to graph.db')
+  .action((name, opts) => {
+    try {
+      snapshotDelete(name, { dbPath: opts.db });
+      console.log(`Snapshot "${name}" deleted.`);
+    } catch (err) {
+      console.error(err.message);
+      process.exit(1);
+    }
+  });
+
 // ─── Embedding commands ─────────────────────────────────────────────────
 
 program
@@ -556,8 +939,16 @@ program
   .option('-k, --kind <kind>', 'Filter by kind: function, method, class')
   .option('--file <pattern>', 'Filter by file path pattern')
   .option('--rrf-k <number>', 'RRF k parameter for multi-query ranking', '60')
+  .option('--mode <mode>', 'Search mode: hybrid, semantic, keyword (default: hybrid)')
   .option('-j, --json', 'Output as JSON')
+  .option('--offset <number>', 'Skip N results (default: 0)')
+  .option('--ndjson', 'Newline-delimited JSON output')
   .action(async (query, opts) => {
+    const validModes = ['hybrid', 'semantic', 'keyword'];
+    if (opts.mode && !validModes.includes(opts.mode)) {
+      console.error(`Invalid mode "${opts.mode}". Valid: ${validModes.join(', ')}`);
+      process.exit(1);
+    }
     await search(query, opts.db, {
       limit: parseInt(opts.limit, 10),
       noTests: resolveNoTests(opts),
@@ -566,6 +957,7 @@ program
       kind: opts.kind,
       filePattern: opts.file,
       rrfK: parseInt(opts.rrfK, 10),
+      mode: opts.mode,
       json: opts.json,
     });
   });
@@ -582,6 +974,9 @@ program
   .option('-T, --no-tests', 'Exclude test/spec files')
   .option('--include-tests', 'Include test/spec files (overrides excludeTests config)')
   .option('-j, --json', 'Output as JSON')
+  .option('--limit <number>', 'Max results to return')
+  .option('--offset <number>', 'Skip N results (default: 0)')
+  .option('--ndjson', 'Newline-delimited JSON output')
   .action(async (dir, opts) => {
     const { structureData, formatStructure } = await import('./structure.js');
     const data = structureData(opts.db, {
@@ -590,41 +985,18 @@ program
       sort: opts.sort,
       full: opts.full,
       noTests: resolveNoTests(opts),
+      limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
+      offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
     });
-    if (opts.json) {
+    if (opts.ndjson) {
+      printNdjson(data, 'directories');
+    } else if (opts.json) {
       console.log(JSON.stringify(data, null, 2));
     } else {
       console.log(formatStructure(data));
     }
   });
 
-program
-  .command('hotspots')
-  .description(
-    'Find structural hotspots: files or directories with extreme fan-in, fan-out, or symbol density',
-  )
-  .option('-d, --db <path>', 'Path to graph.db')
-  .option('-n, --limit <number>', 'Number of results', '10')
-  .option('--metric <metric>', 'fan-in | fan-out | density | coupling', 'fan-in')
-  .option('--level <level>', 'file | directory', 'file')
-  .option('-T, --no-tests', 'Exclude test/spec files from results')
-  .option('--include-tests', 'Include test/spec files (overrides excludeTests config)')
-  .option('-j, --json', 'Output as JSON')
-  .action(async (opts) => {
-    const { hotspotsData, formatHotspots } = await import('./structure.js');
-    const data = hotspotsData(opts.db, {
-      metric: opts.metric,
-      level: opts.level,
-      limit: parseInt(opts.limit, 10),
-      noTests: resolveNoTests(opts),
-    });
-    if (opts.json) {
-      console.log(JSON.stringify(data, null, 2));
-    } else {
-      console.log(formatHotspots(data));
-    }
-  });
-
 program
   .command('roles')
   .description('Show node role classification: entry, core, utility, adapter, dead, leaf')
@@ -668,6 +1040,8 @@ program
   .option('-T, --no-tests', 'Exclude test/spec files')
   .option('--include-tests', 'Include test/spec files (overrides excludeTests config)')
   .option('-j, --json', 'Output as JSON')
+  .option('--offset <number>', 'Skip N results (default: 0)')
+  .option('--ndjson', 'Newline-delimited JSON output')
   .action(async (file, opts) => {
     const { analyzeCoChanges, coChangeData, coChangeTopData, formatCoChange, formatCoChangeTop } =
       await import('./cochange.js');
@@ -694,20 +1068,25 @@ program
 
     const queryOpts = {
       limit: parseInt(opts.limit, 10),
+      offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
       minJaccard: opts.minJaccard ? parseFloat(opts.minJaccard) : config.coChange?.minJaccard,
       noTests: resolveNoTests(opts),
     };
 
     if (file) {
       const data = coChangeData(file, opts.db, queryOpts);
-      if (opts.json) {
+      if (opts.ndjson) {
+        printNdjson(data, 'partners');
+      } else if (opts.json) {
         console.log(JSON.stringify(data, null, 2));
       } else {
         console.log(formatCoChange(data));
       }
     } else {
       const data = coChangeTopData(opts.db, queryOpts);
-      if (opts.json) {
+      if (opts.ndjson) {
+        printNdjson(data, 'pairs');
+      } else if (opts.json) {
         console.log(JSON.stringify(data, null, 2));
       } else {
         console.log(formatCoChangeTop(data));
@@ -736,8 +1115,8 @@ program
       console.error('Provide a function/entry point name or use --list to see all entry points.');
       process.exit(1);
     }
-    if (opts.kind && !ALL_SYMBOL_KINDS.includes(opts.kind)) {
-      console.error(`Invalid kind "${opts.kind}". Valid: ${ALL_SYMBOL_KINDS.join(', ')}`);
+    if (opts.kind && !EVERY_SYMBOL_KIND.includes(opts.kind)) {
+      console.error(`Invalid kind "${opts.kind}". Valid: ${EVERY_SYMBOL_KIND.join(', ')}`);
       process.exit(1);
     }
     const { flow } = await import('./flow.js');
@@ -754,6 +1133,70 @@ program
     });
   });
 
+program
+  .command('dataflow <name>')
+  .description('Show data flow for a function: parameters, return consumers, mutations')
+  .option('-d, --db <path>', 'Path to graph.db')
+  .option('-f, --file <path>', 'Scope to file (partial match)')
+  .option('-k, --kind <kind>', 'Filter by symbol kind')
+  .option('-T, --no-tests', 'Exclude test/spec files from results')
+  .option('--include-tests', 'Include test/spec files (overrides excludeTests config)')
+  .option('-j, --json', 'Output as JSON')
+  .option('--ndjson', 'Newline-delimited JSON output')
+  .option('--limit <number>', 'Max results to return')
+  .option('--offset <number>', 'Skip N results (default: 0)')
+  .option('--impact', 'Show data-dependent blast radius')
+  .option('--depth <n>', 'Max traversal depth', '5')
+  .action(async (name, opts) => {
+    if (opts.kind && !EVERY_SYMBOL_KIND.includes(opts.kind)) {
+      console.error(`Invalid kind "${opts.kind}". Valid: ${EVERY_SYMBOL_KIND.join(', ')}`);
+      process.exit(1);
+    }
+    const { dataflow } = await import('./dataflow.js');
+    dataflow(name, opts.db, {
+      file: opts.file,
+      kind: opts.kind,
+      noTests: resolveNoTests(opts),
+      json: opts.json,
+      ndjson: opts.ndjson,
+      limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
+      offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
+      impact: opts.impact,
+      depth: opts.depth,
+    });
+  });
+
+program
+  .command('cfg <name>')
+  .description('Show control flow graph for a function')
+  .option('-d, --db <path>', 'Path to graph.db')
+  .option('--format <fmt>', 'Output format: text, dot, mermaid', 'text')
+  .option('-f, --file <path>', 'Scope to file (partial match)')
+  .option('-k, --kind <kind>', 'Filter by symbol kind')
+  .option('-T, --no-tests', 'Exclude test/spec files from results')
+  .option('--include-tests', 'Include test/spec files (overrides excludeTests config)')
+  .option('-j, --json', 'Output as JSON')
+  .option('--ndjson', 'Newline-delimited JSON output')
+  .option('--limit <number>', 'Max results to return')
+  .option('--offset <number>', 'Skip N results (default: 0)')
+  .action(async (name, opts) => {
+    if (opts.kind && !EVERY_SYMBOL_KIND.includes(opts.kind)) {
+      console.error(`Invalid kind "${opts.kind}". Valid: ${EVERY_SYMBOL_KIND.join(', ')}`);
+      process.exit(1);
+    }
+    const { cfg } = await import('./cfg.js');
+    cfg(name, opts.db, {
+      format: opts.format,
+      file: opts.file,
+      kind: opts.kind,
+      noTests: resolveNoTests(opts),
+      json: opts.json,
+      ndjson: opts.ndjson,
+      limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
+      offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
+    });
+  });
+
 program
   .command('complexity [target]')
   .description('Show per-function complexity metrics (cognitive, cyclomatic, nesting depth, MI)')
@@ -771,15 +1214,18 @@ program
   .option('-T, --no-tests', 'Exclude test/spec files from results')
   .option('--include-tests', 'Include test/spec files (overrides excludeTests config)')
   .option('-j, --json', 'Output as JSON')
+  .option('--offset <number>', 'Skip N results (default: 0)')
+  .option('--ndjson', 'Newline-delimited JSON output')
   .action(async (target, opts) => {
-    if (opts.kind && !ALL_SYMBOL_KINDS.includes(opts.kind)) {
-      console.error(`Invalid kind "${opts.kind}". Valid: ${ALL_SYMBOL_KINDS.join(', ')}`);
+    if (opts.kind && !EVERY_SYMBOL_KIND.includes(opts.kind)) {
+      console.error(`Invalid kind "${opts.kind}". Valid: ${EVERY_SYMBOL_KIND.join(', ')}`);
       process.exit(1);
     }
     const { complexity } = await import('./complexity.js');
     complexity(opts.db, {
       target,
       limit: parseInt(opts.limit, 10),
+      offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
       sort: opts.sort,
       aboveThreshold: opts.aboveThreshold,
       health: opts.health,
@@ -787,29 +1233,36 @@ program
       kind: opts.kind,
       noTests: resolveNoTests(opts),
       json: opts.json,
+      ndjson: opts.ndjson,
     });
   });
 
 program
-  .command('manifesto')
-  .description('Evaluate manifesto rules (pass/fail verdicts for code health)')
+  .command('ast [pattern]')
+  .description('Search stored AST nodes (calls, new, string, regex, throw, await) by pattern')
   .option('-d, --db <path>', 'Path to graph.db')
+  .option('-k, --kind <kind>', 'Filter by AST node kind (call, new, string, regex, throw, await)')
+  .option('-f, --file <path>', 'Scope to file (partial match)')
   .option('-T, --no-tests', 'Exclude test/spec files from results')
   .option('--include-tests', 'Include test/spec files (overrides excludeTests config)')
-  .option('-f, --file <path>', 'Scope to file (partial match)')
-  .option('-k, --kind <kind>', 'Filter by symbol kind')
   .option('-j, --json', 'Output as JSON')
-  .action(async (opts) => {
-    if (opts.kind && !ALL_SYMBOL_KINDS.includes(opts.kind)) {
-      console.error(`Invalid kind "${opts.kind}". Valid: ${ALL_SYMBOL_KINDS.join(', ')}`);
+  .option('--ndjson', 'Newline-delimited JSON output')
+  .option('--limit <number>', 'Max results to return')
+  .option('--offset <number>', 'Skip N results (default: 0)')
+  .action(async (pattern, opts) => {
+    const { AST_NODE_KINDS, astQuery } = await import('./ast.js');
+    if (opts.kind && !AST_NODE_KINDS.includes(opts.kind)) {
+      console.error(`Invalid AST kind "${opts.kind}". Valid: ${AST_NODE_KINDS.join(', ')}`);
       process.exit(1);
     }
-    const { manifesto } = await import('./manifesto.js');
-    manifesto(opts.db, {
-      file: opts.file,
+    astQuery(pattern, opts.db, {
       kind: opts.kind,
+      file: opts.file,
       noTests: resolveNoTests(opts),
       json: opts.json,
+      ndjson: opts.ndjson,
+      limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
+      offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
     });
   });
 
@@ -823,6 +1276,9 @@ program
   .option('-T, --no-tests', 'Exclude test/spec files from results')
   .option('--include-tests', 'Include test/spec files (overrides excludeTests config)')
   .option('-j, --json', 'Output as JSON')
+  .option('--limit <number>', 'Max results to return')
+  .option('--offset <number>', 'Skip N results (default: 0)')
+  .option('--ndjson', 'Newline-delimited JSON output')
   .action(async (opts) => {
     const { communities } = await import('./communities.js');
     communities(opts.db, {
@@ -831,6 +1287,114 @@ program
       drift: opts.drift,
       noTests: resolveNoTests(opts),
       json: opts.json,
+      limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
+      offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
+      ndjson: opts.ndjson,
+    });
+  });
+
+program
+  .command('triage')
+  .description(
+    'Ranked audit queue by composite risk score (connectivity + complexity + churn + role)',
+  )
+  .option('-d, --db <path>', 'Path to graph.db')
+  .option('-n, --limit <number>', 'Max results to return', '20')
+  .option(
+    '--level <level>',
+    'Granularity: function (default) | file | directory. File/directory level shows hotspots',
+    'function',
+  )
+  .option(
+    '--sort <metric>',
+    'Sort metric: risk | complexity | churn | fan-in | mi (function level); fan-in | fan-out | density | coupling (file/directory level)',
+    'risk',
+  )
+  .option('--min-score <score>', 'Only show symbols with risk score >= threshold')
+  .option('--role <role>', 'Filter by role (entry, core, utility, adapter, leaf, dead)')
+  .option('-f, --file <path>', 'Scope to a specific file (partial match)')
+  .option('-k, --kind <kind>', 'Filter by symbol kind (function, method, class)')
+  .option('-T, --no-tests', 'Exclude test/spec files from results')
+  .option('--include-tests', 'Include test/spec files (overrides excludeTests config)')
+  .option('-j, --json', 'Output as JSON')
+  .option('--offset <number>', 'Skip N results (default: 0)')
+  .option('--ndjson', 'Newline-delimited JSON output')
+  .option('--weights <json>', 'Custom weights JSON (e.g. \'{"fanIn":1,"complexity":0}\')')
+  .action(async (opts) => {
+    if (opts.level === 'file' || opts.level === 'directory') {
+      // Delegate to hotspots for file/directory level
+      const { hotspotsData, formatHotspots } = await import('./structure.js');
+      const metric = opts.sort === 'risk' ? 'fan-in' : opts.sort;
+      const data = hotspotsData(opts.db, {
+        metric,
+        level: opts.level,
+        limit: parseInt(opts.limit, 10),
+        offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
+        noTests: resolveNoTests(opts),
+      });
+      if (opts.ndjson) {
+        printNdjson(data, 'hotspots');
+      } else if (opts.json) {
+        console.log(JSON.stringify(data, null, 2));
+      } else {
+        console.log(formatHotspots(data));
+      }
+      return;
+    }
+
+    if (opts.kind && !EVERY_SYMBOL_KIND.includes(opts.kind)) {
+      console.error(`Invalid kind "${opts.kind}". Valid: ${EVERY_SYMBOL_KIND.join(', ')}`);
+      process.exit(1);
+    }
+    if (opts.role && !VALID_ROLES.includes(opts.role)) {
+      console.error(`Invalid role "${opts.role}". Valid: ${VALID_ROLES.join(', ')}`);
+      process.exit(1);
+    }
+    let weights;
+    if (opts.weights) {
+      try {
+        weights = JSON.parse(opts.weights);
+      } catch {
+        console.error('Invalid --weights JSON');
+        process.exit(1);
+      }
+    }
+    const { triage } = await import('./triage.js');
+    triage(opts.db, {
+      limit: parseInt(opts.limit, 10),
+      offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
+      sort: opts.sort,
+      minScore: opts.minScore,
+      role: opts.role,
+      file: opts.file,
+      kind: opts.kind,
+      noTests: resolveNoTests(opts),
+      json: opts.json,
+      ndjson: opts.ndjson,
+      weights,
+    });
+  });
+
+program
+  .command('owners [target]')
+  .description('Show CODEOWNERS mapping for files and functions')
+  .option('-d, --db <path>', 'Path to graph.db')
+  .option('--owner <owner>', 'Filter to a specific owner')
+  .option('--boundary', 'Show cross-owner boundary edges')
+  .option('-f, --file <path>', 'Scope to a specific file')
+  .option('-k, --kind <kind>', 'Filter by symbol kind')
+  .option('-T, --no-tests', 'Exclude test/spec files')
+  .option('--include-tests', 'Include test/spec files (overrides excludeTests config)')
+  .option('-j, --json', 'Output as JSON')
+  .action(async (target, opts) => {
+    const { owners } = await import('./owners.js');
+    owners(opts.db, {
+      owner: opts.owner,
+      boundary: opts.boundary,
+      file: opts.file || target,
+      kind: opts.kind,
+      noTests: resolveNoTests(opts),
+      json: opts.json,
     });
   });
 
@@ -927,4 +1491,67 @@ program
     }
   });
 
+program
+  .command('batch <command> [targets...]')
+  .description(
+    `Run a query against multiple targets in one call. Output is always JSON.\nValid commands: ${Object.keys(BATCH_COMMANDS).join(', ')}`,
+  )
+  .option('-d, --db <path>', 'Path to graph.db')
+  .option('--from-file <path>', 'Read targets from file (JSON array or newline-delimited)')
+  .option('--stdin', 'Read targets from stdin (JSON array)')
+  .option('--depth <n>', 'Traversal depth passed to underlying command')
+  .option('-f, --file <path>', 'Scope to file (partial match)')
+  .option('-k, --kind <kind>', 'Filter by symbol kind')
+  .option('-T, --no-tests', 'Exclude test/spec files from results')
+  .option('--include-tests', 'Include test/spec files (overrides excludeTests config)')
+  .action(async (command, positionalTargets, opts) => {
+    if (opts.kind && !EVERY_SYMBOL_KIND.includes(opts.kind)) {
+      console.error(`Invalid kind "${opts.kind}". Valid: ${EVERY_SYMBOL_KIND.join(', ')}`);
+      process.exit(1);
+    }
+
+    let targets;
+    try {
+      if (opts.fromFile) {
+        const raw = fs.readFileSync(opts.fromFile, 'utf-8').trim();
+        if (raw.startsWith('[')) {
+          targets = JSON.parse(raw);
+        } else {
+          targets = raw.split(/\r?\n/).filter(Boolean);
+        }
+      } else if (opts.stdin) {
+        const chunks = [];
+        for await (const chunk of process.stdin) chunks.push(chunk);
+        const raw = Buffer.concat(chunks).toString('utf-8').trim();
+        targets = raw.startsWith('[') ? JSON.parse(raw) : raw.split(/\r?\n/).filter(Boolean);
+      } else {
+        targets = splitTargets(positionalTargets);
+      }
+    } catch (err) {
+      console.error(`Failed to parse targets: ${err.message}`);
+      process.exit(1);
+    }
+
+    if (!targets || targets.length === 0) {
+      console.error('No targets provided. Pass targets as arguments, --from-file, or --stdin.');
+      process.exit(1);
+    }
+
+    const batchOpts = {
+      depth: opts.depth ? parseInt(opts.depth, 10) : undefined,
+      file: opts.file,
+      kind: opts.kind,
+      noTests: resolveNoTests(opts),
+    };
+
+    // Multi-command mode: items from --from-file / --stdin may be objects with { command, target }
+    const isMulti = targets.length > 0 && typeof targets[0] === 'object' && targets[0].command;
+    if (isMulti) {
+      const data = multiBatchData(targets, opts.db, batchOpts);
+      console.log(JSON.stringify(data, null, 2));
+    } else {
+      batch(command, targets, opts.db, batchOpts);
+    }
+  });
+
 program.parse();