Skip to content

cli.md

Latest commit

 

History

History
325 lines (233 loc) · 8.24 KB

cli.md

File metadata and controls

325 lines (233 loc) · 8.24 KB
Raw

CLI Reference

The CLI interface (opencode-rag) provides full access to build, manage, and search your project's vector database. It's primarily intended for testing, debugging, and scripting, but works independently of OpenCode.

Global Options

Flag Description
-c, --config <path> Path to config file
-h, --help Show help

Commands

init

Configure the current workspace for OpenCodeRAG.

opencode-rag init [options]

Options:

Flag Default Description
-f, --force false Overwrite existing files
--skip-install false Skip npm install step
--skip-health-check false Skip provider connectivity and model availability check

Creates:

  • .opencode/ directory structure
  • .opencode/plugins/rag-plugin.js — workspace-local plugin fallback
  • .opencode/plugins/rag-tui.js — TUI plugin module
  • .opencode/opencode.json — OpenCode workspace config
  • .opencode/tui.json — TUI plugin settings
  • .opencode/package.json — workspace dependencies
  • opencode-rag.json — runtime configuration
  • .opencode/.gitignore — ignores node_modules/ and rag_db/
  • Runs npm install to install workspace dependencies

Health check: After writing config files, init validates provider connectivity and model availability for all configured models (embedding + description + image description if enabled). For Ollama, if models are missing, you're prompted to pull them automatically. Use --skip-health-check to bypass (e.g., for offline environments).

index

Index workspace files into the vector database.

opencode-rag index [options]

Options:

Flag Default Description
-f, --force false Force full rebuild (clears existing index)
-w, --watch false Watch for file changes and re-index automatically
-c, --config <path> auto-detected Path to config file

How it works:

  1. Scans workspace files matching indexing.includeExtensions
  2. Compares file hashes against the manifest
  3. Clears any files previously flagged with descriptionFailed so they are fully re-indexed
  4. Chunks changed/new files via the appropriate chunker
  5. Generates descriptions (if enabled) and embeddings
  6. Stores vectors in LanceDB and tokens in KeywordIndex
  7. Serializes manifest and keyword index

Incremental: Only changed files are reprocessed. Unchanged files are skipped. Files with descriptionFailed in the manifest are automatically retried.

Full rebuild (--force): Clears the store, clears keyword index, and re-indexes everything.

Watch mode (--watch): Uses chokidar to monitor file changes. Re-indexes debounced changes automatically.

query

Search the indexed codebase.

opencode-rag query <query> [options]

Options:

Flag Default Description
-n, --top-k <number> config default Number of results
-c, --config <path> auto-detected Path to config file

Output: Formatted results showing:

  • File path (relative)
  • Relevance score
  • Language
  • Line range
  • Chunk description
  • Content preview

status

Show index statistics and health.

opencode-rag status [options]

Options:

Flag Default Description
-c, --config <path> auto-detected Path to config file

Shows:

  • Total chunk count
  • Store path
  • Embedding provider and model
  • Number of indexed extensions
  • Manifest status (ok/missing/corrupt)
  • Last indexed timestamp
  • Up-to-date files vs. pending files
  • Keyword index chunk count

list

List all indexed files with chunk counts.

opencode-rag list [options]

Options:

Flag Default Description
-c, --config <path> auto-detected Path to config file

Output: Each indexed file with its chunk count, sorted by file path.

show

Show all chunks for a specific file.

opencode-rag show <file> [options]

Options:

Flag Default Description
-c, --config <path> auto-detected Path to config file

Output: All chunks for the given file path, including:

  • Chunk ID
  • Line range
  • Description
  • Content preview

dump

Dump all indexed chunks (paginated).

opencode-rag dump [options]

Options:

Flag Default Description
--offset <number> 0 Starting offset
--limit <number> 100 Max chunks to dump
-c, --config <path> auto-detected Path to config file

clear

Clear all indexed data.

opencode-rag clear [options]

Options:

Flag Default Description
-c, --config <path> auto-detected Path to config file

Uses store.dropDatabase() for a clean slate, also clears the keyword index and manifest.

setup

Set up the OpenCodeRAG runtime at ~/.opencode/ so OpenCode can discover the plugin.

opencode-rag setup [options]

Options:

Flag Default Description
--check false Check whether the runtime is correctly installed
-f, --force false Force re-setup even if up-to-date
--uninstall false Remove the runtime and cleanup

How it works:

  1. Detects the globally-installed package (npm install -g opencode-rag-plugin)
  2. Creates a junction/symlink at ~/.opencode/node_modules/opencode-rag-plugin pointing to the global npm prefix
  3. Also links @opencode-ai/plugin for OpenCode compatibility
  4. Writes a version marker (.bundle-version)
  5. Verifies the installation

No npm install into ~/.opencode/ is needed — the junction-links resolve transparently through Node.js.

Updating: After npm update -g opencode-rag-plugin, run opencode-rag setup to sync the runtime.

Examples:

# Set up the runtime (after global install)
opencode-rag setup

# Re-sync after update
npm update -g opencode-rag-plugin
opencode-rag setup

# Check status only
opencode-rag setup --check

# Remove the runtime
opencode-rag setup --uninstall

Examples

# Initialize a workspace
opencode-rag init

# Full index
opencode-rag index

# Incremental index with file watching
opencode-rag index --watch

# Force rebuild
opencode-rag index --force

# Semantic search
opencode-rag query "How is authentication handled?"

# Limit results
opencode-rag query "database connection pool" --top-k 5

# Show index status
opencode-rag status

# List indexed files
opencode-rag list

# Show chunks for a file
opencode-rag show src/auth.ts

# Dump first 50 chunks
opencode-rag dump --limit 50

# Clear all data
opencode-rag clear

# Use a custom config
opencode-rag index --config ./config/my-rag-config.json

Evaluation Commands

eval:sessions

List all logged evaluation sessions.

opencode-rag eval:sessions [options]

Options:

Flag Default Description
-c, --config <path> auto-detected Path to config file

Output: Table of sessions with ID, message count, input tokens, RAG context tokens, and cost.

eval:analyze <sessionID>

Analyze token usage for a specific session with RAG impact projection.

opencode-rag eval:analyze <sessionID> [options]

Options:

Flag Default Description
-c, --config <path> auto-detected Path to config file

Output sections:

  • Total input/output/reasoning tokens, cache stats, cost
  • RAG impact: context injected, system guidance overhead, tool call counts
  • Projection: estimated tokens with vs without RAG, net savings percentage
  • Per-query breakdown: input tokens, RAG context, reads, RAG tools, top score

eval:compare <sessionA> <sessionB>

Compare token usage between two sessions (e.g. RAG-on vs RAG-off).

opencode-rag eval:compare <sessionA> <sessionB> [options]

Options:

Flag Default Description
-c, --config <path> auto-detected Path to config file

Output: Formatted comparison table with delta and percentage change for each metric.

See Evaluation documentation for interpretation and configuration guidance.

Programmatic Use

The CLI can also be invoked programmatically:

import { runCli } from "opencode-rag-plugin/library";

await runCli(["query", "auth middleware", "--top-k", "5"]);