hybrid-index

CLI for indexing codebases and running semantic search + code intelligence via the Hybrid Codebase RAG backend.

Table of Contents

• Install
• Quick Start
• Configuration
• Global Options
• Commands
  • init
  • index
  • push
  • remote-index
  • sync
  • bulk-index
  • search
  • impact
  • call-graph
  • status
  • list
  • jobs
  • logs
  • doctor
• JSON Output
• CI / Automation
• Development

Install

npm install -g hybrid-index

Requires Node.js 18+ and git (for index and bulk-index commands).

Quick Start

# 1. Start the backend (Docker)
docker run -p 3000:3000 ghcr.io/zodinet/hybrid-codebase-rag:latest

# 2. Initialize config in your project
hybrid-index init

# 3. Index the current repo (git archive → upload → index)
hybrid-index index --name my-project

# 4. Search your code
hybrid-index search "authentication middleware"

# 5. Understand impact before refactoring
hybrid-index impact validateUser

Configuration

Options are resolved in priority order (highest wins):

| Priority | Source | |----------|--------| | 1 | CLI flags (--server, --key, --project) | | 2 | Environment variables (HYBRID_SERVER, HYBRID_API_KEY, HYBRID_PROJECT) | | 3 | Local config — .hybridindex.yml in current working directory | | 4 | Global config — ~/.hybridindex/config.yaml | | 5 | Defaults (http://localhost:3000) |

Local config (.hybridindex.yml)

Create one interactively with hybrid-index init, or write it manually:

server: http://localhost:3000
project: my-project           # default project id for index/sync/search
api_key_env: HYBRID_API_KEY   # env var that holds your API key
include:
  - "**/*.ts"
  - "**/*.py"
  - docs/**/*.md
exclude:
  - node_modules/**
  - dist/**
incremental: true             # default to incremental sync

Global config (~/.hybridindex/config.yaml)

Shared defaults across all projects on your machine:

server: https://hybrid.example.com
api_key: hx_abc123

Bulk config (bulk: section)

Controls behaviour of bulk-index. Can live in local or global config:

bulk:
  depth: 3          # max directory depth to search for git repos (default: 3)
  concurrency: 2    # concurrent uploads (default: 1)
  exclude:          # glob patterns to skip
    - vendor/*
    - archived/*
  tags:             # tags applied to every discovered repo
    - team:platform
  repos:            # per-repo overrides (keyed by inferred project name)
    my-org/api:
      name: api-gateway       # override project name
      tags: [lang:typescript] # extra tags
    my-org/legacy:
      skip: true              # exclude entirely

Global Options

These flags apply to every command and must come before the command name:

| Flag | Env var | Description | |------|---------|-------------| | --server <url> | HYBRID_SERVER | Backend server URL | | --key <apikey> | HYBRID_API_KEY | API key | | --project <id> | HYBRID_PROJECT | Default project / GitNexus repo id | | --json | — | Print machine-readable JSON instead of formatted output |

hybrid-index --server https://hybrid.example.com --key hx_abc123 --project my-app search "auth"

Commands

init

Create a .hybridindex.yml config file in the current directory.

hybrid-index init [options]

| Option | Description | |--------|-------------| | --server <url> | Backend server URL | | --project <id> | Default project id | | --api-key-env <var> | Env var name that holds the API key | | --incremental | Default to incremental indexing | | --force | Overwrite an existing config file |

Examples

# Interactive — prompts for values
hybrid-index init

# Non-interactive — supply all flags
hybrid-index init --server http://localhost:3000 --project my-project --api-key-env HYBRID_API_KEY

# Overwrite existing config
hybrid-index init --server http://new-server:3000 --force

index

Full index of a project. Operates in two modes depending on whether a project id is configured.

hybrid-index index [options]

| Option | Description | |--------|-------------| | --name <name> | Project name when creating via git archive (default: current directory name) | | --tag <tag...> | Tag(s) to attach; repeatable (e.g. --tag env:ci --tag team:backend) |

Mode 1 — No project id configured (new project)

Runs git archive HEAD on the current working directory, uploads the zip, and creates a new project — all in one step. Equivalent to:

git archive --format=zip HEAD > /tmp/repo.zip
hybrid-index push /tmp/repo.zip --name my-repo

# Archive cwd and push (name inferred from directory)
hybrid-index index

# Explicit name and tags
hybrid-index index --name my-repo --tag env:ci --tag team:platform

# Against a remote backend
hybrid-index --server https://hybrid.example.com --key hx_abc123 index --name my-repo

Mode 2 — Project id configured (re-index existing)

Triggers a full re-index job on the existing project and streams its logs:

# Via config file / env
hybrid-index index

# Via flag
hybrid-index --project proj-123 index

push

Upload a local .zip archive to the backend. Creates a new project and indexes its contents.

hybrid-index push <path> [options]

| Argument | Description | |----------|-------------| | <path> | Path to the .zip archive |

| Option | Description | |--------|-------------| | --name <name> | Project name (default: inferred from zip filename) | | --tag <tag...> | Tag(s) to attach; repeatable |

Examples

# Minimal — name inferred from filename
hybrid-index push dist/my-project.zip

# With name and tags
hybrid-index push dist/my-project.zip --name my-project --tag env:staging --tag team:backend

# Build a zip from git, then push
git archive --format=zip HEAD > /tmp/repo.zip
hybrid-index push /tmp/repo.zip --name my-project

remote-index

Tell the backend to clone and index a remote Git repository directly (no local clone needed).

hybrid-index remote-index <repo-url> [options]

| Argument | Description | |----------|-------------| | <repo-url> | Git repository URL |

| Option | Description | |--------|-------------| | --name <name> | Project name (default: inferred from repo URL) | | --branch <branch> | Branch to clone (default: repo's default branch) | | --pat <token> | Personal access token for private HTTPS repositories | | --tag <tag...> | Tag(s) to attach; repeatable |

Examples

# Public repo
hybrid-index remote-index https://github.com/nestjs/nest.git --name nestjs-core

# Private repo with PAT
hybrid-index remote-index https://github.com/org/private-api.git \
  --pat ghp_xxxx --branch develop --name private-api

# With tags
hybrid-index remote-index https://github.com/org/api.git \
  --tag team:backend --tag lang:typescript

sync

Trigger an incremental re-index (only changed files since the last index) on an existing project and stream its logs.

hybrid-index sync

Requires --project, HYBRID_PROJECT, or project in config.

# Use project from config / env
hybrid-index sync

# Explicit project
hybrid-index --project my-project sync

bulk-index

Scan a directory tree for git repositories, zip each one, and upload them in batch.

hybrid-index bulk-index [path] [options]

| Argument | Description | |----------|-------------| | [path] | Root directory to scan (default: current working directory) |

| Option | Description | |--------|-------------| | --dry-run | Preview which repos would be indexed without uploading | | --depth <n> | Max directory depth to search for git repos (default: 3) | | --concurrency <n> | Number of simultaneous uploads (default: 1) | | --tag <tag...> | Extra tag(s) to add to every repo | | --exclude <glob...> | Glob patterns to skip | | --skip-existing | Skip repos already indexed |

Examples

# Dry run — see what would be indexed
hybrid-index bulk-index /path/to/projects --dry-run

# Index all repos under a directory
hybrid-index bulk-index /path/to/projects

# Concurrency and depth
hybrid-index bulk-index /home/dev --depth 4 --concurrency 3

# With global tags and exclusions
hybrid-index bulk-index . --tag env:ci --exclude vendor/* --exclude archived/*

# Skip repos that are already indexed
hybrid-index bulk-index /path/to/projects --skip-existing

search

Run semantic search across an indexed project.

hybrid-index search <query> [options]

| Argument | Description | |----------|-------------| | <query> | Natural-language search query |

| Option | Description | |--------|-------------| | -k, --top-k <n> | Maximum number of results (default: 10) | | --structural | Augment results with GitNexus execution-flow context |

Examples

# Basic search
hybrid-index search "error handling in API routes"

# Limit results
hybrid-index search "JWT validation" -k 5

# Include call graph / process context
hybrid-index search "database connection pooling" --structural

# JSON for scripting
hybrid-index search "webhook handler" --json | jq '.results[].filePath'

impact

Run GitNexus impact analysis — shows what callers, processes, and modules would be affected by changing a symbol.

hybrid-index impact <symbol> [options]

| Argument | Description | |----------|-------------| | <symbol> | Function, class, or method name |

| Option | Description | |--------|-------------| | -d, --depth <n> | Traversal depth (default: 3) |

Examples

# Who calls validateUser, and what breaks if you change it?
hybrid-index impact validateUser

# Deeper traversal
hybrid-index impact AuthService --depth 5

# JSON output for CI
hybrid-index impact processPayment --json | jq '.risk'

call-graph

Visualise the call graph for a symbol — who calls it and what it calls.

hybrid-index call-graph <symbol> [options]

| Argument | Description | |----------|-------------| | <symbol> | Function, class, or method name |

| Option | Description | |--------|-------------| | --direction <dir> | both (default), callers, or callees |

Examples

# Both directions
hybrid-index call-graph handleRequest

# Only show callers
hybrid-index call-graph processPayment --direction callers

# Only show callees
hybrid-index call-graph DatabaseService --direction callees

status

Show status details for a project.

hybrid-index status [project-id]

The project id can be passed as a positional argument, via --project, HYBRID_PROJECT, or config.

hybrid-index status
hybrid-index status my-project
hybrid-index --project my-project status --json

list

List all indexed projects.

hybrid-index list [options]

| Option | Description | |--------|-------------| | --status <status> | Filter by status: all (default), ready, indexing, error |

hybrid-index list
hybrid-index list --status ready
hybrid-index list --json | jq '.[].name'

jobs

List recent indexing jobs (optionally filtered to the configured project).

hybrid-index jobs
hybrid-index --project my-project jobs
hybrid-index jobs --json

logs

Stream or print logs from a specific indexing job.

hybrid-index logs <job-id>

hybrid-index logs job_abc123
hybrid-index logs job_abc123 --json

doctor

Check environment readiness and CLI/backend configuration. Useful for debugging connectivity issues.

hybrid-index doctor

Checks include:

• git availability and version
• node version
• Backend server reachability
• API key presence

JSON Output

Any command supports --json for machine-readable output, useful for scripting and CI pipelines:

# List projects as JSON
hybrid-index list --json

# Get risk level from impact analysis
hybrid-index --project my-app impact validateUser --json | jq '.risk'

# Extract file paths from search results
hybrid-index search "auth flow" --json | jq '.results[].filePath'

# Check project status in a script
STATUS=$(hybrid-index --project my-app status --json | jq -r '.status')
if [ "$STATUS" != "ready" ]; then echo "Not ready"; exit 1; fi

CI / Automation

GitHub Actions — index on push

- name: Index codebase
  env:
    HYBRID_SERVER: ${{ secrets.HYBRID_SERVER }}
    HYBRID_API_KEY: ${{ secrets.HYBRID_API_KEY }}
  run: |
    npm install -g hybrid-index
    hybrid-index index --name ${{ github.repository }} --tag env:ci --tag branch:${{ github.ref_name }}

Pre-commit check — fail if impact is HIGH

#!/bin/sh
RISK=$(hybrid-index impact "$CHANGED_SYMBOL" --json | jq -r '.risk')
if [ "$RISK" = "HIGH" ] || [ "$RISK" = "CRITICAL" ]; then
  echo "⚠️  Impact risk is $RISK — review callers before committing."
  exit 1
fi

Bulk-index all repos in a monorepo

hybrid-index bulk-index ./services \
  --depth 2 \
  --concurrency 4 \
  --tag env:prod \
  --skip-existing \
  --json | jq '.[] | {name, status}'

Development

# Clone the repo
git clone https://github.com/Zodinet/hybrid-codebase-rag.git
cd hybrid-codebase-rag/cli

# Install dependencies
npm install

# Run in dev mode (no build step)
npm run dev -- --help

# Run tests
npm test

# Build
npm run build

# Publish to npm
npm run publish:npm

# Install locally for end-to-end testing
npm run publish:local