CLI Reference

The dev command-line interface provides local access to dev-agent’s code intelligence features.

Installation


npm install -g dev-agent

Commands

`dev init`

Initialize dev-agent in your repository.


dev init

Creates a .dev-agent.json configuration file with default settings.

`dev index`

Index your repository for semantic search. Indexes code, git history, and GitHub issues/PRs.


dev index .
dev index /path/to/repo

What gets indexed:

✅ Code (always)
✅ Git history (if in a git repo)
✅ GitHub issues/PRs (if gh CLI installed and authenticated)

Shows an upfront “indexing plan” before starting.

Options:

Flag	Description
`-f, --force`	Force re-index even if unchanged
`-v, --verbose`	Show verbose output
`--no-git`	Skip git history indexing
`--no-github`	Skip GitHub issues/PRs indexing
`--git-limit <n>`	Max git commits to index (default: 500)

`dev search`

Search your indexed code semantically.


dev search "authentication logic"
dev search "error handling" --limit 5 --threshold 0.4

Options:

Flag	Description	Default
`-l, --limit <n>`	Maximum results	10
`-t, --threshold <n>`	Minimum similarity (0-1)	0.7
`--json`	Output as JSON	false

Threshold Guide:

0.7+ — Precise matches only
0.4-0.6 — Balanced (good for most searches)
0.25-0.3 — Exploratory (finds related concepts)

`dev explore`

Explore code patterns and relationships.


# Find patterns semantically
dev explore pattern "error handling" --limit 5
 
# Find code similar to a file
dev explore similar path/to/file.ts

Options:

Flag	Description	Default
`-l, --limit <n>`	Maximum results	10
`-t, --threshold <n>`	Minimum similarity	0.7

`dev plan`

Assemble context for implementing a GitHub issue.


dev plan 42
dev plan 42 --include-comments --include-history

Options:

Flag	Description	Default
`--include-comments`	Include issue comments	true
`--include-history`	Include related PRs/issues	true
`--token-budget <n>`	Max tokens for output	4000

`dev gh`

Index and search GitHub issues/PRs.


# Index GitHub metadata (also done by dev index)
dev gh index
 
# Search issues/PRs
dev gh search "authentication bug"
 
# Get context for an issue
dev gh context --issue 42

`dev git`

Index and search git commit history.


# Index git history (also done by dev index)
dev git index
dev git index --limit 1000 --since "6 months ago"
 
# Semantic search over commits
dev git search "authentication fix"
dev git search "bug fix" --limit 5
 
# Show indexed commit stats
dev git stats

Subcommands:

Command	Description
`dev git index`	Index git commit history
`dev git search <query>`	Semantic search over commits
`dev git stats`	Show indexed commit count

Index Options:

Flag	Description	Default
`--limit <n>`	Max commits to index	500
`--since <date>`	Only index commits after date	-

Search Options:

Flag	Description	Default
`--limit <n>`	Max results	10
`--json`	Output as JSON	false

`dev update`

Incrementally update the index with changed files.


dev update

Options:

Flag	Description
`-v, --verbose`	Show verbose output

`dev stats`

Show indexing statistics.


dev stats
dev stats --json

Options:

Flag	Description
`--json`	Output as JSON

`dev clean`

Remove all indexed data.


dev clean --force

Options:

Flag	Description
`-f, --force`	Skip confirmation prompt

`dev storage`

Manage storage locations.


dev storage path     # Show storage path
dev storage size     # Show storage size

`dev compact`

Compact the vector database to reclaim space.


dev compact

MCP Commands

Commands for Model Context Protocol integration with AI tools.

`dev mcp start`

Start the MCP server for AI tool integration.


dev mcp start
dev mcp start --verbose

Options:

Flag	Description	Default
`-t, --transport <type>`	Transport type (stdio/http)	stdio
`-p, --port <port>`	Port for HTTP transport	3000
`-v, --verbose`	Verbose logging	false

`dev mcp install`

Install dev-agent as an MCP server in Claude Code or Cursor.


# Install for Claude Code
dev mcp install
 
# Install for Cursor
dev mcp install --cursor

Options:

Flag	Description
`-r, --repository <path>`	Repository path (default: cwd)
`--cursor`	Install for Cursor instead of Claude Code

`dev mcp uninstall`

Remove dev-agent MCP server from Claude Code or Cursor.


dev mcp uninstall
dev mcp uninstall --cursor

`dev mcp list`

List all configured MCP servers.


dev mcp list
dev mcp list --cursor

Configuration

The .dev-agent.json file configures the indexer:


{
  "repositoryPath": "/path/to/repo",
  "vectorStorePath": ".dev-agent/vectors.lance",
  "embeddingModel": "Xenova/all-MiniLM-L6-v2",
  "dimension": 384,
  "excludePatterns": [
    "**/node_modules/**",
    "**/dist/**",
    "**/.git/**"
  ],
  "languages": ["typescript", "javascript", "markdown"]
}

Examples

Basic Workflow


# Index everything (code, git history, GitHub)
dev index .
 
# Search for code
dev search "user authentication"
 
# Search git history
dev git search "authentication fix"
 
# View statistics
dev stats

Integration with Cursor


# Index your project
dev index .
 
# Install MCP server
dev mcp install --cursor
 
# Restart Cursor - tools are now available!

Scripting with JSON Output


# Get file paths from search
dev search "coordinator" --json | jq '.[].metadata.path' | sort -u
 
# Check if indexed
dev stats --json | jq '.filesIndexed'

Exploratory Search


# Lower threshold for broader matches
dev search "architectural patterns" --threshold 0.25 --limit 10
 
# Find similar code
dev explore similar src/utils/retry.ts --threshold 0.3