How We Refactored a 2,400-Line CLI Monolith into 7 Core Verbs Without Breaking Changes

As TokenCap expanded from a simple repository snapshot generator to a full intelligence engine with graphs, memory loops, and security scanners, our CLI sprawled out of control. We had 21 distinct commands in a single 2,455-line bin/tokencap.js file.

To fix this, we completed a major CLI refactoring around 7 core verbs.

The 7 Core Verbs Hierarchy

1. make (src/cli/make.js): Snapshot generation, watch mode, custom budgeting profiles.
2. ask (src/cli/ask.js): Spatial queries (ask impact, ask dead-code, ask adr).
3. analyze (src/cli/analyze.js): Repo audits (analyze health, analyze debt, analyze security).
4. serve (src/cli/serve.js): Background daemons (serve --daemon, serve --mcp).
5. update (src/cli/update.js): In-place upgrades.
6. help & version: System introspection.

The Silent Alias Strategy

To guarantee that existing scripts and CI workflows did not break:

// bin/tokencap.js excerpt
const ALIASES = {
  graph: ["ask", "impact"],
  capsule: ["make"],
  security: ["analyze", "security"],
  health: ["analyze", "health"],
  mcp: ["serve", "--mcp"]
};

const normalizedArgs = resolveAliases(process.argv.slice(2));

The dispatcher shrank from 2,455 lines down to 234 lines of clean routing logic, with handlers decoupled into modular, testable files in src/cli/.

Inspect the CLI architecture at tokencap.vansharora.app