Documentation

Quickstart

Get up and running in under a minute.

npm install -g @optiqcode/cli
optiq login
optiq index ~/my-project
optiq search "how does auth work"

Installation

Requires Node.js 18 or later.

npm install -g @optiqcode/cli

Verify:

optiq --version

Authentication

Optiq uses device-based authentication. Running optiq login opens your browser where you verify your identity with email OTP and Turnstile captcha.

optiq login

Tokens are stored locally at ~/.optiq/auth.json. They auto-refresh on 401.

optiq whoami    # Check current account
optiq logout    # Clear session

Agent Authentication

AI agents authenticate with Optiq using API keys (Bearer tokens). This guide covers programmatic authentication without browser interaction.

Step 1: Get an API key

Generate an API key from your dashboard. Keys start with sk- and can be scoped to specific permissions.

Step 2: Set the key

Pass the key as a Bearer token in the Authorization header:

curl -X POST https://api.optiqcode.com/api/v1/search \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"query": "auth middleware", "repo_id": "my-project"}'

Or set it as an environment variable for the CLI:

export OPTIQ_API_KEY="sk-your-api-key"
optiq search "auth middleware"

Step 3: Scoped permissions

API keys can be scoped to limit access. Request only the permissions your agent needs:

MCP server authentication

The local MCP server (optiq mcp) uses the session from optiq login. The remote MCP endpoint at https://api.optiqcode.com/mcp requires a Bearer token.

OAuth discovery

Authorization server metadata is published at /.well-known/oauth-authorization-server per RFC 8414. Agents can discover endpoints, supported scopes, and PKCE (S256) support automatically.

Indexing

Indexing reads your local files, uploads them to the Optiq engine, and builds a semantic graph with embeddings powered by Voyage AI.

# Index current directory
optiq index

# Index a specific path
optiq index ~/projects/my-app

# Force a clean re-index
optiq index --fresh

How it works

1. CLI collects all source files (skips binaries, node_modules, .git, etc.)
2. Files are uploaded to the Optiq API
3. Engine parses code with tree-sitter, extracts symbols and relationships
4. Voyage AI generates embeddings for semantic search
5. A graph of nodes and edges is built for structural retrieval

Incremental indexing

By default, re-indexing only processes changed files. Content fingerprints determine what needs updating. Use --fresh to force a full rebuild.

Auto-reindex (MCP)

When running as an MCP server, Optiq watches indexed directories for file changes and automatically re-indexes in the background with a 3-second debounce.

Search

Optiq combines semantic vector search, keyword search (Tantivy), and graph traversal for accurate code retrieval.

Natural language

optiq search "how does the auth middleware validate tokens"
optiq search "where are database connections configured"

Structured filters

optiq search "symbol:handleAuth"
optiq search "file:middleware type:function"
optiq search "def:createUser"
optiq search "uses:prisma.user"

Options

API Reference

Base URL: https://api.optiqcode.com

Authenticate with Authorization: Bearer <token> or an API key (sk-...).

Query

{
  "query": "how does authentication work",
  "repo_id": "my-app-abc12345",
  "limit": 10,
  "intent": "understand"
}

Index files

{
  "files": [
    { "path": "src/auth.ts", "content": "..." },
    { "path": "src/db.ts", "content": "..." }
  ],
  "repo_id": "my-app-abc12345",
  "embed": true,
  "incremental": true,
  "fresh": false
}

Index status

List repositories

Delete repository

Rate Limits

Every API response includes rate limit headers so agents can self-throttle and avoid getting blocked.

Response headers

Limits by tier

Handling 429 responses

When rate limited, the API returns HTTP 429 with a Retry-After header. Agents should wait the specified number of seconds before retrying. Implement exponential backoff for repeated 429s.

Streaming

For long-running operations like indexing large repositories, the API supports Server-Sent Events (SSE) for real-time progress updates.

Streaming index progress

Add Accept: text/event-stream to receive SSE updates during indexing:

curl -N -H "Authorization: Bearer sk-your-key" \
  -H "Accept: text/event-stream" \
  https://api.optiqcode.com/api/v1/repos

# SSE events:
# event: progress
# data: {"files_processed": 42, "files_total": 100, "status": "indexing"}
#
# event: complete
# data: {"repo_id": "abc123", "status": "ready", "files_indexed": 100}

Streaming search

Search results can be streamed as they are ranked. Each event contains a single result:

curl -N -H "Authorization: Bearer sk-your-key" \
  -H "Accept: text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"query": "auth middleware", "stream": true}' \
  https://api.optiqcode.com/api/v1/search

# event: result
# data: {"file_path": "src/auth.ts", "score": 0.92, ...}
#
# event: done
# data: {"total": 8, "query_time_ms": 340}

Error Handling

All errors return structured JSON with a machine-readable code, human-readable message, and a resolution hint.

Error format

{
  "error": {
    "code": "invalid_request",
    "message": "Missing required field: query",
    "hint": "Include a 'query' string in the request body"
  }
}

HTTP status codes

MCP error responses

The MCP server returns standard JSON-RPC 2.0 errors with structured codes:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Invalid params: 'query' is required",
    "data": { "hint": "Pass a non-empty query string" }
  }
}

MCP Server

The CLI doubles as an MCP (Model Context Protocol) server over stdio. AI agents can index, search, and manage repositories through it.

optiq mcp

Exposed tools

Auto-reindex

After the first optiq_index call, the MCP server watches the directory for changes and incrementally re-indexes in the background (3s debounce).

Integrations

Claude Code

claude mcp add optiq -- optiq mcp

Cursor

// .cursor/mcp.json
{
  "mcpServers": {
    "optiq": {
      "command": "optiq",
      "args": ["mcp"]
    }
  }
}

Claude Desktop

// claude_desktop_config.json
{
  "mcpServers": {
    "optiq": {
      "command": "optiq",
      "args": ["mcp"]
    }
  }
}

Any MCP client

Any client supporting stdio transport works. Point it at optiq mcp.

CLI Reference