Skip to content
This repository was archived by the owner on Sep 26, 2026. It is now read-only.

cli-commands.md

Latest commit

 

History

History
320 lines (247 loc) · 10.7 KB

cli-commands.md

File metadata and controls

320 lines (247 loc) · 10.7 KB
Raw

CLI Commands Reference

Complete reference for all Code Explorer commands with tested examples.

Quick Start

# 1. Analyze your codebase
code-explorer analyze ./src --exclude tests --exclude .venv

# 2. View statistics
code-explorer stats

# 3. Find who calls a function
code-explorer impact src/module.py:function_name

analyze - Build Dependency Graph

Analyze Python codebase and extract functions, classes, variables, and their relationships.

Synopsis:

code-explorer analyze PATH [OPTIONS]

Common Usage:

# Basic analysis with exclusions
code-explorer analyze ./src --exclude tests --exclude .venv

# Include virtual environment (override default exclusion)
code-explorer analyze . --include .venv --include venv

# Force full refresh (clears database)
code-explorer analyze ./src --refresh

# Maximum parallelism (16 workers)
code-explorer analyze ./src --workers 16

Options:

  • PATH (required): Directory containing Python code
  • --exclude PATTERN: Exclude patterns (repeatable)
  • --include PATTERN: Override default exclusions (repeatable)
  • --workers N: Parallel workers (default: 4)
  • --db-path PATH: Database location (default: .code-explorer/graph.db)
  • --refresh: Force full re-analysis

Note: To analyze .venv, use --include .venv --include venv to override both default exclusions.

Output Example:

Analyzing codebase at: /home/user/project/src
Database location: /home/user/project/.code-explorer/graph.db
Excluding: __pycache__, .pytest_cache, htmlcov, dist, build, .git, .worktrees, .venv, venv

Analysis complete!
┏━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━┓
┃ Metric                 ┃ Count ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━┩
│ Total files analyzed   │   156 │
│ Files processed        │    12 │
│ Total functions        │   842 │
│ Total variables        │   234 │
└────────────────────────┴───────┘

╭──────────── ⏱ Performance Metrics ─────────────╮
│  Total analysis time: 3.45s                    │
│                                                │
│  Breakdown:                                    │
│    • File analysis: 1.20s                      │
│    • Node insertion: 0.85s                     │
│    • Edge insertion: 0.12s                     │
│    • Call resolution: 0.98s                    │
│    • Call edge insertion: 0.30s                │
╰────────────────────────────────────────────────╯

Default Exclusions: .venv, venv, __pycache__, .pytest_cache, htmlcov, dist, build, .git

stats - Codebase Statistics

Show overview statistics and most-called functions.

Synopsis:

code-explorer stats [OPTIONS]

Common Usage:

# Basic statistics (uses .code-explorer/graph.db in current directory)
code-explorer stats

# Show top 20 most-called functions
code-explorer stats --top 20

# Custom database path
code-explorer stats --db-path ./src/.code-explorer/graph.db

Options:

  • --db-path PATH: Database location (default: ./.code-explorer/graph.db)
  • --top N: Number of top functions (default: 10)

Output Example:

┏━━━━━━━━━━━━━━━━━━━┳━━━━━━━┓
┃ Metric            ┃ Count ┃
┡━━━━━━━━━━━━━━━━━━━╇━━━━━━━┩
│ Files             │   156 │
│ Functions         │   842 │
│ Variables         │   234 │
│ Function calls    │  2631 │
└───────────────────┴───────┘

Top 10 Most-Called Functions:
┏━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━┓
┃ #  ┃ Function        ┃ File           ┃ Calls ┃
┡━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━┩
│ 1  │ validate_input  │ utils/core.py  │   127 │
│ 2  │ log_event       │ logging.py     │    89 │
└────┴─────────────────┴────────────────┴───────┘

impact - Function Impact Analysis

Find who calls a function (upstream) or what a function calls (downstream).

Synopsis:

code-explorer impact TARGET [OPTIONS]

Common Usage:

# Find who calls this function (upstream impact)
code-explorer impact src/module.py:process_data

# Find what this function calls (downstream impact)
code-explorer impact src/module.py:process_data --downstream

# Limit search depth to 2 levels
code-explorer impact src/api.py:endpoint --max-depth 2

Options:

  • TARGET (required): Format file.py:function_name
  • --downstream: Show downstream (what function calls)
  • --max-depth N: Maximum traversal depth (default: 5)
  • --db-path PATH: Database location

Output Example:

Upstream impact for 'process_data':
┏━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━┓
┃ Function         ┃ File          ┃ Line  ┃ Depth ┃
┡━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━┩
│ handle_request   │ api/views.py  │   45  │   1   │
│ batch_process    │ workers.py    │  123  │   1   │
│ main_loop        │ main.py       │   89  │   2   │
└──────────────────┴───────────────┴───────┴───────┘

search - Find Code by Keyword or Meaning (Experimental)

Search function/class source code with BM25 lexical search, typo-tolerant fuzzy search, or semantic (vector) search, then print an LLM-ready context bundle for the top hit (the hit itself plus its direct callers/callees, with source attached). See LatticeDB Migration for the design behind this.

Different database from every other command. analyze/stats/ visualize all use the KuzuDB database at .code-explorer/graph.db, and impact has moved onto the search index instead (see below). search builds its own LatticeDB index instead (.code-explorer/graph.lattice, or graph_vectors.lattice for --semantic, since vector dimensions are fixed when a LatticeDB index is created and can't be added to an existing one) — it does not read or write the Kuzu database analyze builds. Running search for the first time against a directory re-parses and re-indexes it; there's no incremental update yet, so re-run with --reindex after the code changes.

Synopsis:

code-explorer search QUERY [PATH] [OPTIONS]

Common Usage:

# BM25 keyword search (default)
code-explorer search "resolve call" src

# Typo-tolerant fuzzy search
code-explorer search "refesh_token" --fuzzy

# Semantic search -- finds conceptually related code with no keyword overlap
# Requires a local Ollama server with the nomic-embed-text model:
#   ollama pull nomic-embed-text
code-explorer search "walking a syntax tree recursively" src --semantic

# Just the ranked hits, skip the context bundle
code-explorer search "resolve call" --no-context --limit 10

# Force a fresh index after the code has changed
code-explorer search "resolve call" --reindex

Options:

  • QUERY (required): Text to search for
  • PATH: Directory to search (default: current directory)
  • --limit N: Maximum results (default: 5)
  • --fuzzy: Typo-tolerant search instead of BM25
  • --semantic: Vector search instead of BM25 (needs local Ollama, see above)
  • --no-context: Only show the results table, skip the context bundle
  • --reindex: Force a fresh index instead of reusing an existing one

Notes:

  • Only Function and Class nodes are indexed (their source code), and only those two node types are covered by ingestion today (no Variable, Import, Decorator, Attribute, Exception, Module yet) — see the migration doc's Implementation Status section for what's covered.
  • The context bundle is assembled for the top-ranked Function hit only (Class hits have no call graph to expand); if every result is a Class, search says so instead of erroring.
  • --fuzzy and --semantic are separate modes, not merged/reranked together (that's a possible future "hybrid retrieval" phase, not implemented).

visualize - Generate Mermaid Diagram

Create visual dependency graph as Mermaid diagram.

Synopsis:

code-explorer visualize TARGET [OPTIONS]

Common Usage:

# Visualize entire module
code-explorer visualize src/module.py

# Focus on specific function with custom output
code-explorer visualize src/module.py --function process_data --output deps.md

# Control traversal depth
code-explorer visualize utils.py --function helper --max-depth 2

Options:

  • TARGET (required): File to visualize (e.g., module.py)
  • --function NAME: Specific function to highlight
  • --output PATH: Output file (default: graph.md)
  • --max-depth N: Traversal depth (default: 3, function-only)
  • --db-path PATH: Database location

View Output:

Troubleshooting

"Could not set lock" Error

# Fix: Close other processes using the database
pkill code-explorer
rm .code-explorer/graph.db-lock  # If needed

Database Not Found

# Run analyze first
code-explorer analyze ./src

# Or specify correct path
code-explorer stats --db-path ./src/.code-explorer/graph.db

No Files Found

Check that .venv, tests are in exclude list:

code-explorer analyze ./src --exclude .venv --exclude tests

Performance Tips

  1. Use exclusions: --exclude .venv --exclude tests (faster analysis)
  2. Increase workers: --workers 16 on multi-core systems
  3. Limit depth: --max-depth 3 for faster impact queries
  4. Incremental updates: Skip --refresh to only re-analyze changed files

Files

  • .code-explorer/graph.db - Default database location (KuzuDB format)
  • graph.md - Default visualization output

Exit Codes

  • 0 - Success
  • 1 - Error (missing database, invalid arguments, analysis failure)