gh-cadrianmae-claude-marketplace-plugins-semantic-search/skills/semantic-search/references/cli_basics.md

Odino CLI Basics

Reference guide for odino CLI syntax, commands, and options.

Installation

# Install via pipx (recommended)
pipx install odino

# Verify installation
odino --version

Core Commands

odino index

Index a directory for semantic search.

# Index current directory
odino index

# Index specific directory
odino index /path/to/project

# Specify model (recommended: BGE for efficiency)
odino index --model BAAI/bge-small-en-v1.5

# Force reindex (ignores existing index)
odino index --force

Configuration:

• Creates .odino/ directory in indexed location
• Stores config in .odino/config.json
• Stores embeddings in .odino/chroma_db/

Default model: EmmanuelEA/eea-embedding-gemma (600MB) Recommended model: BAAI/bge-small-en-v1.5 (133MB, faster)

odino query

Search indexed directory using natural language.

# Basic search
odino query -q "authentication logic"

# Search with custom number of results
odino query -q "database connections" -n 10

# Search specific path
odino query -q "error handling" -p /path/to/indexed/dir

Options:

• -q, --query <QUERY> - Natural language search query (required)
• -n, --num-results <N> - Number of results to return (default: 5)
• -p, --path <PATH> - Path to indexed directory (default: current dir)

Output format:

Score: 0.85 | Path: src/auth/middleware.js
Score: 0.78 | Path: src/auth/tokens.js
Score: 0.72 | Path: src/utils/validation.js

odino status

Show indexing status and statistics.

# Status for current directory
odino status

# Status for specific path
odino status -p /path/to/project

Output includes:

• Number of indexed files
• Total chunks generated
• Model name
• Index location
• Last modified date

Configuration File

Location: .odino/config.json in indexed directory

{
  "model_name": "BAAI/bge-small-en-v1.5",
  "embedding_batch_size": 16,
  "chunk_size": 512,
  "chunk_overlap": 50
}

Key settings:

• model_name - Embedding model to use
• embedding_batch_size - Batch size for GPU/CPU (16 for GPU, 8 for CPU)
• chunk_size - Token length for text chunks
• chunk_overlap - Overlap between chunks

.odinoignore File

Create .odinoignore in project root to exclude files/directories (gitignore syntax):

# Build artifacts
build/
dist/
*.pyc
__pycache__/

# Dependencies
node_modules/
venv/
.venv/

# Config files
.env
.env.local
*.secret

Model Comparison

Model	Size	Params	MTEB Score	Speed
eea-embedding-gemma	600MB	308M	69.67	Slower
bge-small-en-v1.5	133MB	33M	~62-63	Faster

Recommendation: Use BGE for most cases (smaller, faster, good quality)

Common CLI Patterns

Index with BGE model:

odino index --model BAAI/bge-small-en-v1.5

Search from subdirectory:

# Requires finding .odino directory first (see SKILL.md)
cd project/src/utils
odino query -q "validation" -p ../..

Reindex after code changes:

odino index --force

Check if directory is indexed:

if [[ -d .odino ]]; then
    echo "Directory is indexed"
    odino status
else
    echo "Directory is not indexed"
fi

Performance Tips

1. Use BGE model - 78% smaller, 90% fewer parameters, only ~7 point MTEB drop
2. Adjust batch size - Use 16 for GPU, 8 for CPU
3. Use .odinoignore - Exclude build artifacts, dependencies, config files
4. GPU acceleration - Much faster indexing if CUDA available
5. Chunking strategy - Default 512 tokens works well for most code

Troubleshooting

"Command not found: odino"

# Ensure pipx bin directory is in PATH
export PATH="$HOME/.local/bin:$PATH"

# Or reinstall
pipx install odino

"No index found"

# Check for .odino directory
ls -la .odino

# If missing, index first
odino index --model BAAI/bge-small-en-v1.5

GPU out of memory

# Reduce batch size in .odino/config.json
{
  "embedding_batch_size": 8  # or even 4
}

# Then reindex
odino index --force

Slow indexing

# Use smaller model
odino index --model BAAI/bge-small-en-v1.5

# Reduce batch size if GPU memory limited
# Edit .odino/config.json: "embedding_batch_size": 8

Exit Codes

• 0 - Success
• 1 - General error (no index, invalid path, etc.)
• 2 - Invalid arguments

Environment Variables

Odino respects standard environment variables:

• CUDA_VISIBLE_DEVICES - GPU selection
• HF_HOME - Hugging Face cache directory (for model downloads)