CLI Reference

Complete reference for all 38 Nomik CLI commands with real examples and expected output.

Installation

Terminal

npm install -g @nomik-ai/cli

Verify

$ nomik --version
1.0.0

Core Commands

`nomik init`

Initialize a new project — starts Neo4j via Docker and creates the project config.

Terminal

$ nomik init

✓ Neo4j container started (neo4j:5-community)
✓ Neo4j is ready at bolt://localhost:7687
✓ Created .nomik/project.json (project: my-api)
✓ Schema initialized (17 node types, 19 edge types)

Ready! Run 'nomik scan .' to build your knowledge graph.

`nomik scan <path>`

Parse all supported files and ingest nodes and edges into Neo4j.

Terminal

$ nomik scan .

Scanning: /Users/dev/my-api
  Parsing...  312 files (TypeScript: 278, Python: 25, SQL: 9)
  Extracting... functions, classes, routes, DB ops, events, metrics
  Ingesting... 2847 nodes, 6204 edges

✓ Scan complete in 4.2s
  Files:     312
  Functions: 2,847
  Classes:   89
  Routes:    15
  DB Tables: 3
  Env Vars:  12
  Git SHA:   a1b2c3d (feat: add payment endpoint)

Scan a specific directory with project name

$ nomik scan ./src --project my-api

`nomik scan:incremental`

Git diff-based selective re-scan — only files changed since the last commit are re-parsed.

Terminal

$ nomik scan:incremental .

Last scan: a1b2c3d (2 minutes ago)
Current:   e4f5g6h

Changed files: 3
  M src/services/payment.ts
  M src/api/checkout.ts
  A src/services/refund.ts

✓ Incremental scan complete in 0.8s (3 files, 47 nodes, 112 edges)

`nomik watch [path]`

Continuous file monitoring with real-time reindex and impact warnings.

Terminal

$ nomik watch .

Watching: /Users/dev/my-api (500ms debounce)

[14:32:15] Changed: src/services/payment.ts
  ✓ Re-indexed in 0.3s (12 nodes, 28 edges)
  ⚠️ HIGH IMPACT: processPayment has 23 callers across 8 files
  ⚠️ DB IMPACT: writes to payments table

[14:32:45] Changed: src/api/checkout.ts
  ✓ Re-indexed in 0.2s (8 nodes, 15 edges)

`nomik status`

Check Neo4j connection and display project statistics.

Terminal

$ nomik status

Neo4j: ✓ Connected (bolt://localhost:7687)
Project: my-api

Code:
  Files:      312    Functions:  2,847    Classes:    89
  Variables:  156    Modules:    78

API & Routes:
  Routes:     15     External:   5

Data:
  DB Tables:  3      DB Columns: 24       Env Vars:   12

Infrastructure:
  Queue Jobs: 4      Metrics:    8        Spans:      3
  Topics:     2      Events:     6        Cron Jobs:  2

Security:
  Issues:     0

Edges: 6,204 total
  CALLS: 3,412  CONTAINS: 1,891  DEPENDS_ON: 456  IMPORTS: 312  ...

`nomik doctor`

Full diagnostic of your Nomik setup.

Terminal

$ nomik doctor

✓ Node.js:      v22.4.0 (>= 20 required)
✓ pnpm:         9.1.0
✓ Neo4j:        Connected (5.18.0 Community)
  Nodes: 2,847  Edges: 6,204
✓ Project:      my-api (.nomik/project.json)
✓ Rules:        .nomik/rules.yaml (9 built-in + 2 custom)
✓ MCP Server:   dist/mcp-server.js (found)
✓ Git:          a1b2c3d (clean)
✓ Cursor:       .cursor/mcp.json (configured)
⚠ Windsurf:     Not configured (run 'nomik setup-windsurf')
✓ Docker:       docker compose up (neo4j running)

`nomik query "<cypher>"`

Execute a raw Cypher query against the graph.

Terminal

$ nomik query "MATCH (f:Function) WHERE f.isAsync = true RETURN f.name, f.filePath LIMIT 5"

┌─────────────────────┬──────────────────────────────────────┐
│ f.name              │ f.filePath                           │
├─────────────────────┼──────────────────────────────────────┤
│ processPayment      │ src/services/payment.ts              │
│ handleRefund        │ src/services/refund.ts               │
│ sendNotification    │ src/services/notification.ts         │
│ generateReport      │ src/jobs/reporting.ts                │
│ validateUser        │ src/middleware/auth.ts                │
└─────────────────────┴──────────────────────────────────────┘

JSON output

$ nomik query "MATCH (r:Route) RETURN r.method, r.path" --json

`nomik recent`

List recently modified nodes.

Terminal

$ nomik recent --since 24h --limit 10

Recently modified (last 24 hours):
  Function  processPayment       src/services/payment.ts      2 hours ago
  Function  handleRefund         src/services/refund.ts       2 hours ago
  Route     POST /api/checkout   src/api/checkout.ts          3 hours ago
  File      payment.ts           src/services/payment.ts      2 hours ago
  ...

Analysis Commands

`nomik impact <symbol>`

Downstream impact analysis — find everything that breaks if a symbol changes.

Terminal

$ nomik impact processPayment

Impact analysis for: processPayment (Function)
Defined in: src/services/payment.ts:45-89

Depth 1 (direct callers):
  Route     POST /api/checkout     src/api/checkout.ts:12
  Function  handleBatchPayment     src/services/batch.ts:34
  Function  retryPayment           src/services/retry.ts:8

Depth 2 (indirect):
  Route     POST /api/batch        src/api/batch.ts:5
  CronJob   retry_failed           src/jobs/retry.ts:1

DB operations:
  WRITES_TO  payments table
  READS_FROM orders table

Total impact: 5 nodes across 4 files

With depth control

$ nomik impact processPayment --depth 5

`nomik explain <symbol>`

Full context for a symbol — callers, callees, file location, edges.

Terminal

$ nomik explain processPayment

processPayment (Function)
  File:     src/services/payment.ts:45-89
  Async:    true
  Exported: true
  Params:   orderId: string, amount: number

Calls (outgoing):
  → orderService.getOrder       src/services/order.ts:12
  → prisma.payment.create       (DB write → payments table)
  → stripe.charges.create       (External API → Stripe)
  → eventBus.emit               (Event → payment.completed)
  → paymentCounter.inc          (Metric → payment_total)

Called By (incoming):
  ← POST /api/checkout          src/api/checkout.ts:12
  ← handleBatchPayment          src/services/batch.ts:34
  ← retryPayment                src/services/retry.ts:8

Edges: 5 outgoing, 3 incoming

`nomik pr-impact`

Analyze the blast radius of changes in the current branch.

Terminal

$ nomik pr-impact

PR Impact Analysis (feature/payment-v2 → main)

Changed files: 3
  M src/services/payment.ts    (processPayment, validateAmount)
  M src/api/checkout.ts        (checkoutHandler)
  A src/services/refund.ts     (handleRefund)

Blast radius:
  Affected routes:     3 (POST /checkout, POST /refund, GET /payments)
  Affected functions:  12
  Affected DB tables:  2 (payments, refunds)
  Affected tests:      4 files

Risk level: MEDIUM
  ⚠ processPayment has 23 callers
  ⚠ payments table has 4 readers

Recommendation: Run affected tests before merging.

JSON output for CI

$ nomik pr-impact --json > impact.json

`nomik test-impact <symbol>`

Find all test files that should be re-run after a change.

Terminal

$ nomik test-impact processPayment

Test files affected by changes to processPayment:
  src/__tests__/payment.test.ts          (direct import)
  src/__tests__/checkout.test.ts         (calls processPayment via route)
  src/__tests__/batch.test.ts            (calls handleBatchPayment)
  src/__tests__/integration/api.test.ts  (mocks processPayment)

`nomik rename <old> <new>`

Graph-aware rename showing all affected files.

Terminal

$ nomik rename processPayment handlePayment

Rename: processPayment → handlePayment

Definition:
  src/services/payment.ts:45  export async function processPayment(...)

Callers (3):
  src/api/checkout.ts:15      processPayment(orderId, amount)
  src/services/batch.ts:38    await processPayment(item.orderId, item.amount)
  src/services/retry.ts:12    await processPayment(payment.orderId, payment.amount)

Importers (2):
  src/api/checkout.ts:1       import { processPayment } from '../services/payment'
  src/services/batch.ts:2     import { processPayment } from './payment'

Total: 6 references in 4 files

Use --apply to execute the rename:
  nomik rename processPayment handlePayment --apply

`nomik migrate <symbol>`

Guided migration plan with risk assessment.

Terminal

$ nomik migrate processPayment --to src/services/payment-v2.ts

Migration Plan: processPayment → src/services/payment-v2.ts

Risk Level: HIGH (23 callers, 2 DB tables, 1 external API)

Steps:
  1. Create src/services/payment-v2.ts with new implementation
  2. Add re-export shim in src/services/payment.ts:
     export { handlePayment as processPayment } from './payment-v2'
  3. Update direct importers (4 files):
     - src/api/checkout.ts
     - src/services/batch.ts
     - src/services/retry.ts
     - src/__tests__/payment.test.ts
  4. Run affected tests (4 files)
  5. Remove re-export shim after all consumers updated

Affected DB operations: payments (WRITE), orders (READ)
Affected external APIs: Stripe

`nomik diff <sha1> <sha2>`

Architecture drift between two scans.

Terminal

$ nomik diff a1b2c3d e4f5g6h

Architecture Drift: a1b2c3d → e4f5g6h

New files: 2
  + src/services/refund.ts
  + src/__tests__/refund.test.ts

Removed files: 0

New functions: 3
  + handleRefund (src/services/refund.ts:5)
  + validateRefund (src/services/refund.ts:23)
  + refundHandler (src/api/refund.ts:8)

New call edges: 5
  + POST /api/refund → refundHandler → handleRefund
  + handleRefund → prisma.payment.update
  + handleRefund → stripe.refunds.create

Removed call edges: 0

`nomik service-links`

Cross-service dependencies through queues, events, and APIs.

Terminal

$ nomik service-links

Cross-Service Dependencies:

Queue: payment-queue (Bull)
  Producer: processPayment        src/services/payment.ts:67
  Consumer: paymentWorker          src/workers/payment.ts:5

Event: payment.completed
  Emitter:  processPayment        src/services/payment.ts:72
  Listener: sendReceipt           src/services/email.ts:15
  Listener: updateAnalytics       src/services/analytics.ts:8

Topic: order-events (Kafka)
  Producer: createOrder           src/services/order.ts:45
  Consumer: orderProcessor        src/workers/orders.ts:12

Quality and CI Commands

`nomik rules`

Evaluate architecture rules.

Terminal

$ nomik rules

Architecture Rules Evaluation:

✓ max-dead-code        0 / 5      PASS
✗ max-god-files        4 / 3      FAIL (error)
  - src/controllers/listing.controller.ts (18 functions)
  - src/services/user.service.ts (14 functions)
  - src/socket.ts (12 functions)
  - src/utils/helpers.ts (11 functions)
✓ max-duplicates       1 / 2      PASS
✓ max-function-callers 23 / 50    PASS
✓ max-db-writes        2 / 3      PASS
✓ no-circular-imports  0 cycles   PASS
⚠ max-function-lines   1 / 200    WARN (warning)
  - src/services/payment.ts:processPayment (210 lines)
✓ max-file-lines       0 / 1000   PASS
✓ max-security-issues  0 / 0      PASS

Custom rules:
✓ no-direct-db-in-controllers   0 violations   PASS

Result: 1 error, 1 warning

Initialize rules config

$ nomik rules --init
✓ Created .nomik/rules.yaml with default thresholds

`nomik guard`

Quality gate for CI and pre-commit.

Terminal

$ nomik guard --ci

PASS dead_code: 0/5
PASS god_files: 1/3
PASS duplicates: 0/2

All checks passed.

Options

nomik guard                         # Interactive output with colors
nomik guard --ci                    # CI mode (exit code 1 on failure)
nomik guard --json                  # JSON output for automation
nomik guard --god-file-threshold 20 # Custom threshold (default: 15)
nomik guard --install-hook          # Install as git pre-commit hook
nomik guard --uninstall-hook        # Remove the pre-commit hook

The pre-commit hook runs npx @nomik-ai/cli guard --ci before every commit. If the guard fails, the commit is blocked. Use --uninstall-hook to remove it.

`nomik audit`

Dependency vulnerability check with graph blast radius.

Terminal

$ nomik audit

Dependency Audit:

⚠ lodash@4.17.20 — Prototype Pollution (HIGH)
  Blast radius: 12 files import lodash
    src/utils/helpers.ts        (_.merge, _.get, _.set)
    src/services/transform.ts   (_.mapValues)
    src/api/middleware.ts        (_.pick)
    ... 9 more files

⚠ axios@0.21.0 — SSRF Vulnerability (MEDIUM)
  Blast radius: 3 files import axios
    src/services/payment.ts     (stripe API calls)
    src/services/email.ts       (SendGrid API calls)
    src/services/search.ts      (Algolia API calls)

2 vulnerabilities found (1 high, 1 medium)

`nomik ci`

Unified CI pipeline — runs everything in one command.

Terminal

$ nomik ci

[1/4] Scanning...
  ✓ 312 files, 2847 nodes, 6204 edges (4.2s)

[2/4] Rules evaluation...
  ✓ 8/9 rules passed, 1 warning (0.3s)

[3/4] Quality gate...
  ✓ All thresholds met (0.1s)

[4/4] Dependency audit...
  ⚠ 2 vulnerabilities (1 high, 1 medium) (1.8s)

Result: PASS (with warnings)

Skip scan if graph is up to date

$ nomik ci --skip-scan

Documentation and Reporting

`nomik onboard`

One-command codebase briefing.

Terminal

$ nomik onboard

📋 Codebase Briefing — my-api (scanned 2026-02-20)

Stats:
  2,847 functions across 312 files
  15 routes (8 GET, 4 POST, 2 PUT, 1 DELETE)
  3 DB tables: users, listings, messages
  5 external APIs: Stripe, SendGrid, Algolia, S3, Datadog
  12 environment variables (3 required, 9 optional)
  4 queue jobs, 2 cron jobs, 8 metrics, 3 spans

Language Distribution:
  TypeScript: 89% (278 files)
  Python:      8% (25 files)
  SQL:         3% (9 files)

Health:
  Dead code:   0 functions
  God files:   3 (socket.ts, listing.controller.ts, user.service.ts)
  Duplicates:  2 groups
  Security:    0 issues

High-Risk Functions (most callers):
  processPayment     23 callers across 8 files
  validateUser       19 callers across 6 files
  sendNotification   15 callers across 5 files

`nomik wiki`

Generate markdown documentation from the graph.

Terminal

$ nomik wiki --out ./wiki

Generating documentation...
  ✓ wiki/README.md            (index with stats and file list)
  ✓ wiki/modules/             (per-module detail pages)
    - payment.ts.md           (5 functions, 2 routes, 1 DB table)
    - user.service.ts.md      (14 functions, 3 routes)
    - order.ts.md             (8 functions, 1 route, 2 DB tables)
    ... 42 more modules

✓ Generated 45 files in ./wiki

`nomik changelog`

Auto-generate changelog from graph changes.

Terminal

$ nomik changelog --since 7d

Changelog (last 7 days):

Added:
  + Function handleRefund      src/services/refund.ts
  + Route POST /api/refund     src/api/refund.ts
  + DBTable refunds            (3 columns)

Modified:
  ~ Function processPayment   src/services/payment.ts (added error handling)
  ~ Route POST /api/checkout   src/api/checkout.ts (added validation)

Removed:
  - Function legacyPayment    src/services/legacy.ts

`nomik badge`

Generate health badges for your README.

Terminal

$ nomik badge

Add these to your README.md:

[![Dead Code](https://img.shields.io/badge/dead_code-0-brightgreen)](...)
[![God Files](https://img.shields.io/badge/god_files-3-yellow)](...)
[![Duplicates](https://img.shields.io/badge/duplicates-2-yellow)](...)
[![Security](https://img.shields.io/badge/security-0_issues-brightgreen)](...)

Architecture Commands

`nomik communities`

Detect functional clusters using Union-Find algorithm.

Terminal

$ nomik communities

Functional Clusters:

Cluster 1: Payment Module (cohesion: 0.87)
  Members: 12 functions
  Internal edges: 28    External edges: 4
  Key functions: processPayment, validateAmount, calculateTax

Cluster 2: User Authentication (cohesion: 0.92)
  Members: 8 functions
  Internal edges: 18    External edges: 2
  Key functions: validateUser, generateToken, refreshToken

Cluster 3: Order Processing (cohesion: 0.78)
  Members: 15 functions
  Internal edges: 32    External edges: 8
  Key functions: createOrder, updateOrder, cancelOrder

`nomik flows`

Trace execution flows from entry points through the call graph.

Terminal

$ nomik flows

Execution Flows:

POST /api/checkout
  → checkoutHandler
    → validateUser
    → processPayment
      → prisma.payment.create    (DB WRITE → payments)
      → stripe.charges.create    (External API → Stripe)
      → eventBus.emit            (Event → payment.completed)
    → sendConfirmation
      → sendgrid.send            (External API → SendGrid)

CronJob: monthly_billing (0 0 1 * *)
  → generateReport
    → prisma.payment.findMany    (DB READ → payments)
    → s3.putObject               (External API → S3)

Event: payment.completed
  → sendReceipt                  (via LISTENS_TO)
  → updateAnalytics              (via LISTENS_TO)

IDE Setup Commands

One-command configuration for each supported AI editor.

Terminal

$ nomik setup-cursor

✓ Created .cursor/mcp.json
  Server:  @nomik-ai/cli (stdio)
  Neo4j:   bolt://localhost:7687
  Project: my-api
  Role:    dev (full access)

Restart Cursor to activate. Then ask:
  "What MCP tools do you have access to?"

Command	Config File
`nomik setup-cursor`	`.cursor/mcp.json` (project root)
`nomik setup-windsurf`	`~/.codeium/windsurf/mcp_config.json`
`nomik setup-claude`	`%APPDATA%\Claude\claude_desktop_config.json` (Windows) or `~/Library/Application Support/Claude/` (macOS)
`nomik setup-antigravity`	Platform-specific `mcp_config.json`

Server Commands

`nomik serve`

Start the MCP server and visualization dashboard.

Terminal

$ nomik serve

MCP Server:  stdio (ready for IDE connections)
Viz Dashboard: http://localhost:3333
  2D Graph (Cytoscape.js) + 3D Graph (Three.js)
  Search, filters, impact overlay, detail panel

`nomik dashboard`

Start a REST API server with 14 endpoints.

Terminal

$ nomik dashboard

REST API running at http://localhost:4242

Endpoints:
  GET /api/stats           GET /api/health
  GET /api/onboard         GET /api/rules
  GET /api/dead-code       GET /api/god-files
  GET /api/duplicates      GET /api/communities
  GET /api/flows           GET /api/projects
  GET /api/impact?symbol=  GET /api/explain?symbol=
  GET /api/test-impact?symbol=
  GET /api/service-links   GET /api/search?q=

Project Management

Multiple projects in a single Neo4j database via projectId isolation.

Terminal

$ nomik project list

Projects:
  * my-api        (active)    312 files, 2847 nodes
    frontend      (inactive)  156 files, 1204 nodes
    shared-lib    (inactive)   45 files,  234 nodes

$ nomik project create mobile-app
✓ Created project: mobile-app

$ nomik project switch mobile-app
✓ Switched to project: mobile-app

$ nomik project info
Project: mobile-app
  Files:     0
  Functions: 0
  Status:    Empty (run 'nomik scan .' to populate)

Config is stored in .nomik/project.json. All nodes carry a projectId — queries automatically filter by the active project.

On this page