Skip to content

cli.md

Latest commit

 

History

History
198 lines (150 loc) · 8.15 KB

cli.md

File metadata and controls

198 lines (150 loc) · 8.15 KB

CLI Gallery (Human-readable)

codebase-context exposes its tools as a local CLI so humans can:

  • Onboard themselves onto an unfamiliar repo
  • Debug what the MCP server is doing
  • Use outputs in CI/scripts (via --json)

Output depends on the repo you run it against. The examples below are illustrative (paths, counts, and detected frameworks will vary).

The CLI is intentionally single-project per invocation. MCP multi-project routing and trusted-root auto-discovery are only for the MCP server; the CLI still targets one root via CODEBASE_ROOT or the current working directory.

How to run

# Run from a repo root, or set CODEBASE_ROOT explicitly:
CODEBASE_ROOT=/path/to/repo npx -y codebase-context status

# Every command supports --json (machine output). Human mode is default.
npx -y codebase-context patterns --json

ASCII fallback

If your terminal doesn’t render Unicode box-drawing cleanly:

CODEBASE_CONTEXT_ASCII=1 npx -y codebase-context patterns

Commands

  • metadata — tech stack overview
  • patterns — team conventions + adoption/trends
  • search --query <q> — ranked results; add --intent edit for a preflight card
  • refs --symbol <name> — concrete reference evidence
  • cycles — circular dependency detection
  • status — index status/progress
  • reindex — rebuild index (full or incremental)
  • style-guide — find style guide sections in docs
  • memory list|add|remove — manage team memory (stored in .codebase-context/memory.json)

metadata

npx -y codebase-context metadata

Example output:

┌─ codebase-context [monorepo] ────────────────────────────────────────┐
│                                                                      │
│ Framework: Angular unknown   Architecture: mixed                     │
│ 130 files · 24,211 lines · 1077 components                           │
│                                                                      │
│ Dependencies: @huggingface/transformers · @lancedb/lancedb ·         │
│ @modelcontextprotocol/sdk · @typescript-eslint/typescript-estree ·   │
│ chokidar · fuse.js (+14 more)                                        │
│                                                                      │
└──────────────────────────────────────────────────────────────────────┘

patterns

npx -y codebase-context patterns

Example output (truncated):

┌─ Team Patterns ──────────────────────────────────────────────────────┐
│                                                                      │
│ UNIT TEST FRAMEWORK                                                  │
│      USE: Vitest – 96% adoption                                      │
│ alt  CAUTION: Jest – 4% minority pattern                             │
│                                                                      │
│ STATE MANAGEMENT                                                     │
│      PREFER: RxJS – 63% adoption                                     │
│ alt  Redux-style store – 25%                                         │
│                                                                      │
└──────────────────────────────────────────────────────────────────────┘

search

npx -y codebase-context search --query "file watcher" --intent edit --limit 3

Example output (truncated):

┌─ Search: "file watcher" ─── intent: edit ────────────────────────────┐
│ Quality: ok (1.00)                                                   │
│ Ready to edit: YES                                                   │
│                                                                      │
│ Best example: index.ts                                               │
└──────────────────────────────────────────────────────────────────────┘

1.  src/core/file-watcher.ts:44-74
    confidence: ██████████ 1.18
    typescript module in file-watcher.ts: startFileWatcher :: (...)

refs

npx -y codebase-context refs --symbol "startFileWatcher" --limit 10

Example output (truncated):

┌─ startFileWatcher ─── 11 references ─── static analysis ─────────────┐
│                                                                      │
│ startFileWatcher                                                     │
│ │                                                                    │
│ ├─ file-watcher.test.ts:5                                            │
│ │   import { startFileWatcher } from '../src/core/file-watcher....   │
│                                                                      │
└──────────────────────────────────────────────────────────────────────┘

cycles

npx -y codebase-context cycles --scope src

Example output:

┌─ Circular Dependencies ──────────────────────────────────────────────┐
│                                                                      │
│ No cycles found  ·  98 files  ·  260 edges  ·  2.7 avg deps          │
│                                                                      │
└──────────────────────────────────────────────────────────────────────┘

status

npx -y codebase-context status

Example output:

┌─ Index Status ───────────────────────────────────────────────────────┐
│                                                                      │
│ State: ready                                                         │
│ Root:  /path/to/repo                                                 │
│                                                                      │
│ → Run `reindex` to re-index (`--incremental` skips unchanged).       │
│                                                                      │
└──────────────────────────────────────────────────────────────────────┘

reindex

npx -y codebase-context reindex
npx -y codebase-context reindex --incremental --reason "changed watcher logic"

MCP server mode: if you're running codebase-context as an MCP server (long-running process), the index auto-refreshes via a file watcher — you don't need to call reindex between edits. Use reindex for one-shot CLI runs or to force a full rebuild.

style-guide

npx -y codebase-context style-guide --query "naming"

Example output:

No style guides found.
  Hint: Try broader terms like 'naming', 'patterns', 'testing', 'components'

memory

npx -y codebase-context memory list
npx -y codebase-context memory list --query "watcher"

npx -y codebase-context memory add \
  --type gotcha \
  --category tooling \
  --memory "Use pnpm, not npm" \
  --reason "Workspace support and speed"

npx -y codebase-context memory remove <id>