cli-reference.md

CLI Reference

CocoSearch provides a command-line interface for indexing and searching code. Output is JSON by default (for scripting/MCP); use --pretty for human-readable output.

Indexing Commands

uv run cocosearch index <path> [options]

Index a codebase for semantic search.

Flag	Description	Default
-n, --name	Index name	Derived from directory
-i, --include	Include file patterns (repeatable)	See defaults below
-e, --exclude	Exclude file patterns (repeatable)	None
--no-gitignore	Ignore .gitignore patterns	Respects .gitignore

Example:

uv run cocosearch index ./my-project --name myproject

Searching Commands

uv run cocosearch search <query> [options] uv run cocosearch search --interactive

Search indexed code using natural language.

Flag	Description	Default
-n, --index	Index to search	Auto-detect from cwd
-l, --limit	Max results	10
--lang	Filter by language	None
--min-score	Minimum similarity (0-1)	0.3
-A, --after-context	Lines to show after match	Smart expand
-B, --before-context	Lines to show before match	Smart expand
-C, --context	Lines before and after	Smart expand
--no-smart	Disable smart context expansion	Off
--hybrid	Force hybrid search	Auto-detect
--symbol-type	Filter by symbol type (repeatable)	None
--symbol-name	Filter by symbol name pattern	None
--no-cache	Bypass query cache (for debugging)	Off
-i, --interactive	Enter REPL mode	Off
--indexes	Comma-separated index names for cross-index search	None
--pretty	Human-readable output	JSON

Examples:

# Basic search
uv run cocosearch search "authentication logic" --pretty

# Filter by language
uv run cocosearch search "error handling" --lang python

# Inline language filter
uv run cocosearch search "database connection lang:go"

# Cross-index search across multiple projects
uv run cocosearch search "auth middleware" --indexes api-server,shared-libs --pretty

# Interactive mode
uv run cocosearch search --interactive

Pipeline Analysis

uv run cocosearch analyze <query> [options]

Run the search pipeline with stage-by-stage diagnostics. Shows query analysis, mode selection, cache status, vector search results, keyword search results, RRF fusion breakdown, definition boost effects, filtering, and timing.

Flag	Description	Default
-n, --index	Index to search	Auto-detect from cwd
-l, --limit	Max results	10
--lang	Filter by language	None
--min-score	Minimum similarity (0-1)	0.3
--hybrid	Force hybrid search	Auto-detect
--symbol-type	Filter by symbol type (repeatable)	None
--symbol-name	Filter by symbol name pattern	None
--no-cache	Bypass query cache	Off
--json	Output as JSON (default: Rich)	Off

Examples:

# Analyze why a query returns specific results
uv run cocosearch analyze "getUserById"

# JSON output for scripting
uv run cocosearch analyze "database connection pool" --json

# Analyze with language filter
uv run cocosearch analyze "error handling" --lang python

Managing Indexes

List indexes: uv run cocosearch list [--pretty]

Show all available indexes.

uv run cocosearch list --pretty

Index statistics: uv run cocosearch stats [index] [--pretty]

Show statistics for one or all indexes. Includes file count, chunk count, size, language distribution, and parse health.

uv run cocosearch stats myproject --pretty

Flag	Description	Default
--pretty	Human-readable output	JSON
--json	Machine-readable JSON output	Off
-v, --verbose	Show symbol type breakdown	Off
--all	Show stats for all indexes	Off
--show-failures	Show individual file parse failure details	Off
--staleness-threshold	Days before staleness warning	7
--live	Terminal dashboard (multi-pane layout)	Off
--watch	Auto-refresh dashboard (requires --live)	Off
--refresh-interval	Refresh interval in seconds for --watch	1.0

Parse health is shown by default when available. It displays a percentage of files that parsed cleanly along with a per-language breakdown (ok, partial, error, no grammar).

To see individual file failure details (file paths and error types), use the --show-failures flag:

uv run cocosearch stats myproject --pretty --show-failures

Clear index: uv run cocosearch clear <index> [--force] [--pretty]

Delete an index and all its data (including the associated parse results table). Prompts for confirmation unless --force.

uv run cocosearch clear myproject --force

List supported languages: uv run cocosearch languages [--json]

Show all languages CocoSearch can index with extensions and symbol support.

uv run cocosearch languages

Start MCP server: uv run cocosearch mcp

Start the MCP server for LLM integration. Typically invoked by MCP clients, not directly.

uv run cocosearch mcp  # Runs until killed, used by Claude/OpenCode

Dependency Graph Commands

uv run cocosearch deps extract <path>

Extract dependency edges from all indexed files. Parses import/require/uses statements across 8 languages (Python, JavaScript/TypeScript, Go, Docker Compose, GitHub Actions, Terraform, Helm) and stores directed edges with resolved file paths. Runs as a separate pass after indexing.

uv run cocosearch deps extract .

uv run cocosearch deps show <file>

Show dependencies and dependents for a specific file. Lists both what the file imports (dependencies) and what imports the file (dependents).

uv run cocosearch deps show src/cocosearch/deps/extractor.py

uv run cocosearch deps tree <file> [--depth N] [--type TYPE] [--json]

Show the transitive forward dependency tree for a file — what does this file depend on, recursively?

Flag	Description	Default
--depth	Maximum traversal depth	5
--type	Filter by edge type (import/call/reference)	None
--json	Output as JSON instead of Rich tree	Off

uv run cocosearch deps tree src/cocosearch/cli.py --depth 3
uv run cocosearch deps tree src/cocosearch/cli.py --json

uv run cocosearch deps impact <file> [--depth N] [--type TYPE] [--json]

Show the reverse impact tree — what would be affected if this file changes?

Flag	Description	Default
--depth	Maximum traversal depth	5
--type	Filter by edge type (import/call/reference)	None
--json	Output as JSON instead of Rich tree	Off

uv run cocosearch deps impact src/cocosearch/search/db.py --depth 2
uv run cocosearch deps impact src/cocosearch/search/db.py --json

uv run cocosearch deps stats

Show dependency graph statistics (total edges, files with dependencies, per-type and per-language breakdowns, top files by connection count).

uv run cocosearch deps stats

The --deps flag on the index command combines indexing with dependency extraction:

uv run cocosearch index . --deps

Configuration Generation

Initialize project configuration: uv run cocosearch init [options]

Creates a cocosearch.yaml starter configuration file in the current directory. After creating the config file, interactively offers to:

1. Add a CocoSearch tool routing table to CLAUDE.md (local project or global ~/.claude/CLAUDE.md)
2. Add a CocoSearch tool routing table to AGENTS.md (local project or global ~/.config/opencode/AGENTS.md)
3. Register CocoSearch MCP server with OpenCode (local or global opencode.json)
4. Install CocoSearch workflow skills for OpenCode (local or global skills directory)
5. Install CocoSearch plugin for Claude Code (via claude CLI)

Flag	Description
--no-claude-md	Skip the CLAUDE.md tool routing prompt
--no-agents-md	Skip the AGENTS.md tool routing prompt (OpenCode)
--no-opencode-mcp	Skip the OpenCode MCP server registration prompt
--no-opencode-skills	Skip the OpenCode workflow skills installation prompt
--no-claude-mcp	Skip the Claude Code plugin installation prompt

# Interactive: creates cocosearch.yaml, then prompts for all integrations
uv run cocosearch init

# Non-interactive: creates cocosearch.yaml only
uv run cocosearch init --no-claude-md --no-agents-md --no-opencode-mcp --no-opencode-skills --no-claude-mcp

All interactive prompts are skipped automatically when stdin is not a TTY (e.g., in CI pipelines or when piping input).

Configuration Commands

Check configuration and connectivity: uv run cocosearch config check

Validates environment variables and checks connectivity to PostgreSQL, Ollama, and the embedding model. Returns exit code 0 if all checks pass, 1 if any fail.

uv run cocosearch config check

Output includes an environment variable table and a connectivity table:

Service	Status	Details
PostgreSQL	✓ connected
Ollama	✓ connected
Model (nomic-embed-text)	✓ available

If a service is unreachable, the status shows ✗ unreachable with a remediation hint (e.g., Run: docker compose up -d for PostgreSQL, Run: docker compose --profile ollama up -d for Ollama). The model check is skipped if Ollama is unreachable.

Show resolved configuration: uv run cocosearch config show

Display the fully resolved configuration with all sources and precedence levels.

Show config file path: uv run cocosearch config path

Display the path to the config file, or indicate if none is found.

Observability

Monitor index health, language distribution, symbol breakdown, and parse health.

Index Statistics

uv run cocosearch stats myproject --pretty

Shows file count, chunk count, size, staleness warnings, language distribution with bar charts, and parse health summary.

Parse Health

Parse health tracks how well tree-sitter parsed each indexed file. It is displayed by default in the stats output:

uv run cocosearch stats myproject --pretty

For detailed failure information including file paths and error types:

uv run cocosearch stats myproject --pretty --show-failures

JSON Output

Machine-readable stats for automation:

uv run cocosearch stats myproject --json

Dashboard

Web-based stats visualization:

uv run cocosearch dashboard
# Opens browser to http://localhost:8080

The dashboard displays real-time index health with language distribution charts.