Client CLI Guide

The codechunking-client is a standalone CLI tool for interacting with the CodeChunking API. It outputs structured JSON for easy consumption by AI agents, automation scripts, and CI/CD pipelines.

Overview

Key Features:

JSON-formatted output for all commands
Consistent error codes for programmatic handling
No CGO dependencies (distributable as a static binary)
Built-in polling for async operations (--wait flag)

Use Cases:

AI agent integration (Claude Code, GitHub Copilot, etc.)
Shell script automation
CI/CD pipeline integration
Interactive CLI usage

Installation

Build from Source

# Build for current platform
make build-client

# Binary location
./bin/codechunking-client --help

Cross-Platform Builds

# Build for all platforms
make build-client-cross

# Outputs:
# - bin/codechunking-client-linux-amd64
# - bin/codechunking-client-darwin-amd64
# - bin/codechunking-client-darwin-arm64

Quick Start

# Check API server health
./bin/codechunking-client health

# Add a repository and wait for indexing
./bin/codechunking-client repos add https://github.com/user/repo --wait

# Search for code
./bin/codechunking-client search "authentication middleware" --limit 5

# List all repositories
./bin/codechunking-client repos list

Commands Reference

Global Flags

All commands support these flags:

Flag	Default	Description
`--api-url`	`http://localhost:8080`	API server URL
`--timeout`	`30s`	Request timeout (Go duration format)

health

Check API server health status.

codechunking-client health

Output:

{
  "success": true,
  "data": {
    "status": "healthy",
    "version": "1.0.0",
    "dependencies": {
      "database": "up",
      "nats": "up"
    }
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

repos

Repository management commands.

repos list

List all repositories with optional filtering.

codechunking-client repos list [flags]

Flag	Default	Description
`-l, --limit`	`20`	Maximum repositories to return
`-o, --offset`	`0`	Number to skip (pagination)
`--status`	-	Filter by status: `pending`, `cloning`, `processing`, `completed`, `failed`, `archived`
`--name`	-	Filter by repository name
`--sort`	-	Sort order: `created_at:asc`, `created_at:desc`, `name:asc`, `name:desc`

Examples:

# List first 10 repositories
codechunking-client repos list --limit 10

# List completed repositories only
codechunking-client repos list --status completed

# Sort by name
codechunking-client repos list --sort name:asc

repos get

Get details for a specific repository.

codechunking-client repos get <repository-uuid>

Example:

codechunking-client repos get 550e8400-e29b-41d4-a716-446655440000

repos add

Add a new repository for indexing.

codechunking-client repos add <repository-url> [flags]

Flag	Default	Description
`--name`	-	Custom repository name
`--description`	-	Repository description
`--branch`	-	Branch to index (default: repository default)
`-w, --wait`	`false`	Wait for indexing to complete
`--poll-interval`	`5s`	Status check frequency (with `--wait`)
`--wait-timeout`	`30m`	Maximum wait duration (with `--wait`)

Examples:

# Add repository (async)
codechunking-client repos add https://github.com/user/repo

# Add and wait for completion
codechunking-client repos add https://github.com/user/repo --wait

# Add with custom name
codechunking-client repos add https://github.com/user/repo --name "My Project"

search

Perform semantic code search across indexed repositories.

codechunking-client search "<query>" [flags]

Flag	Default	Description
`-l, --limit`	`20`	Maximum results
`--offset`	`0`	Skip results (pagination)
`--repo-ids`	-	Filter by repository UUIDs (comma-separated)
`--repo-names`	-	Filter by repository names (comma-separated)
`--languages`	-	Filter by languages: `go`, `python`, `javascript`, etc.
`--file-types`	-	Filter by extensions: `.go`, `.py`, `.js`, etc.
`-t, --threshold`	`0.6`	Minimum similarity (0.0-1.0)
`-s, --sort`	`relevance`	Sort order
`--types`	-	Semantic types: `function`, `class`, `interface`, `method`, etc.
`--entity-name`	-	Exact entity name match
`--visibility`	-	Visibility scope: `public`, `private`

Examples:

# Basic search
codechunking-client search "error handling middleware"

# Search in Go files only
codechunking-client search "database connection" --languages go

# Search functions only with high similarity
codechunking-client search "authentication" --types function --threshold 0.8

# Search in specific repository
codechunking-client search "API endpoint" --repo-names "my-project"

jobs get

Get the status of an indexing job.

codechunking-client jobs get <repository-uuid> <job-uuid>

Example:

codechunking-client jobs get 550e8400-e29b-41d4-a716-446655440000 660e8400-e29b-41d4-a716-446655440001

Output:

{
  "success": true,
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "repository_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "files_processed": 150,
    "chunks_created": 1200,
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-01-15T10:05:00Z"
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

JSON Output Format

All commands output a consistent JSON envelope to stdout:

Success Response

{
  "success": true,
  "data": { ... },
  "timestamp": "2024-01-15T10:30:00Z"
}

Error Response

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Repository not found",
    "details": { ... }
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

Error Codes

Code	Description	Common Causes
`INVALID_CONFIG`	Configuration validation failed	Missing API URL, invalid timeout
`CLIENT_ERROR`	Failed to create HTTP client	Internal error
`CONNECTION_ERROR`	Network connectivity issue	Server unreachable, DNS failure
`TIMEOUT_ERROR`	Request timed out	Slow server, network issues
`NOT_FOUND`	Resource not found (HTTP 404)	Invalid UUID, deleted resource
`SERVER_ERROR`	Server error (HTTP 500)	API server issue
`API_ERROR`	Generic API error	Various API-level errors
`INVALID_ARGUMENT`	Invalid command argument	Bad UUID format, missing required arg

Agent Integration

CLAUDE.md Snippet

Add this to your project's CLAUDE.md file to give AI agents context about the CLI:

### Client CLI (codechunking-client)

The `codechunking-client` CLI outputs JSON for AI agent and automation consumption.

**Build:** `make build-client` → `bin/codechunking-client`

**Commands:**
- `codechunking-client health` - Check API server health
- `codechunking-client repos list [--limit N] [--status S]` - List repositories
- `codechunking-client repos get <uuid>` - Get repository details
- `codechunking-client repos add <url> [--wait]` - Add and index repository
- `codechunking-client search "<query>" [--limit N] [--languages L]` - Semantic code search
- `codechunking-client jobs get <repo-id> <job-id>` - Get indexing job status

**Global Flags:**
- `--api-url string` (default: http://localhost:8080) - API server URL
- `--timeout duration` (default: 30s) - Request timeout

**Environment Variables:**
- `CODECHUNK_CLIENT_API_URL` - Override API URL
- `CODECHUNK_CLIENT_TIMEOUT` - Override timeout

**JSON Output Envelope:**
All commands output JSON to stdout:
- Success: `{"success": true, "data": {...}, "timestamp": "..."}`
- Error: `{"success": false, "error": {"code": "...", "message": "..."}, "timestamp": "..."}`

**Error Codes:** `INVALID_CONFIG`, `CONNECTION_ERROR`, `TIMEOUT_ERROR`, `NOT_FOUND`, `SERVER_ERROR`, `API_ERROR`, `INVALID_ARGUMENT`

Example Agent Prompts

Use these prompts with Claude Code or other AI agents:

Index a repository:

Use the codechunking-client to add https://github.com/user/repo and wait for indexing to complete. Parse the JSON output to confirm success.

Search for code patterns:

Use the codechunking-client to search for "error handling" patterns in Go files. Show me the top 5 results with their file paths and similarity scores.

Check repository status:

Use the codechunking-client to list all repositories and their indexing status. Tell me which ones are still processing.

Shell Script Examples

Parse JSON with jq

#!/bin/bash

# Search and extract file paths
./bin/codechunking-client search "database connection" | \
  jq -r '.data.results[].file_path'

# Check if request succeeded
result=$(./bin/codechunking-client repos list)
if echo "$result" | jq -e '.success' > /dev/null; then
  echo "Success!"
  echo "$result" | jq '.data.repositories[].name'
else
  echo "Error: $(echo "$result" | jq -r '.error.message')"
  exit 1
fi

Add Repository and Wait

#!/bin/bash

# Add repository and capture job info
result=$(./bin/codechunking-client repos add https://github.com/user/repo --wait)

if echo "$result" | jq -e '.success' > /dev/null; then
  repo_id=$(echo "$result" | jq -r '.data.id')
  echo "Repository indexed: $repo_id"
else
  error_code=$(echo "$result" | jq -r '.error.code')
  echo "Failed with error: $error_code"
  exit 1
fi

CI/CD Integration

# GitHub Actions example
steps:
  - name: Index Repository
    run: |
      result=$(./bin/codechunking-client repos add ${{ github.repository }} --wait --wait-timeout 10m)
      if ! echo "$result" | jq -e '.success' > /dev/null; then
        echo "Indexing failed: $(echo "$result" | jq -r '.error.message')"
        exit 1
      fi
      echo "REPO_ID=$(echo "$result" | jq -r '.data.id')" >> $GITHUB_ENV

  - name: Search for Security Issues
    run: |
      ./bin/codechunking-client search "sql injection vulnerability" \
        --repo-ids ${{ env.REPO_ID }} \
        --threshold 0.7 | jq '.data.results'

Configuration

Environment Variables

Variable	Description
`CODECHUNK_CLIENT_API_URL`	API server URL (overrides `--api-url`)
`CODECHUNK_CLIENT_TIMEOUT`	Request timeout (overrides `--timeout`)

Configuration Priority

CLI flags (highest priority)
Environment variables
Default values (lowest priority)

Examples

# Use environment variables
export CODECHUNK_CLIENT_API_URL=http://api.example.com:8080
export CODECHUNK_CLIENT_TIMEOUT=60s
./bin/codechunking-client repos list

# Override with flags
./bin/codechunking-client --api-url http://localhost:9090 repos list

Common Workflows

Index and Search a New Repository

# 1. Add repository and wait for completion
./bin/codechunking-client repos add https://github.com/user/repo --wait

# 2. Search for code
./bin/codechunking-client search "authentication" --languages go --limit 10

Monitor Indexing Progress

# 1. Add repository (don't wait)
result=$(./bin/codechunking-client repos add https://github.com/user/repo)
repo_id=$(echo "$result" | jq -r '.data.id')
job_id=$(echo "$result" | jq -r '.data.current_job_id')

# 2. Poll job status
while true; do
  status=$(./bin/codechunking-client jobs get "$repo_id" "$job_id" | jq -r '.data.status')
  echo "Status: $status"

  if [[ "$status" == "completed" || "$status" == "failed" ]]; then
    break
  fi

  sleep 5
done

Batch Search Multiple Repositories

# Get all repository IDs
repo_ids=$(./bin/codechunking-client repos list --status completed | \
  jq -r '.data.repositories[].id' | paste -sd,)

# Search across all repositories
./bin/codechunking-client search "security vulnerability" \
  --repo-ids "$repo_ids" \
  --threshold 0.8 \
  --limit 50

Troubleshooting

Connection Refused

{"success":false,"error":{"code":"CONNECTION_ERROR","message":"connection refused"},"timestamp":"..."}

Solution: Ensure the API server is running (make dev-api) and accessible at the configured URL.

Timeout Errors

{"success":false,"error":{"code":"TIMEOUT_ERROR","message":"request timed out"},"timestamp":"..."}

Solution: Increase timeout with --timeout 60s or CODECHUNK_CLIENT_TIMEOUT=60s.

Invalid UUID

{"success":false,"error":{"code":"INVALID_ARGUMENT","message":"invalid UUID format"},"timestamp":"..."}

Solution: Ensure you're using valid UUID format (e.g., 550e8400-e29b-41d4-a716-446655440000).

Home

Configuration

[📖 Configuration Reference](configuration reference) - Complete reference guide
Configuration
API Configuration
Database Configuration
Gemini Configuration
Git Configuration
Logging Configuration
Middleware Configuration
NATS Configuration
Worker Configuration

Usage Guides

Performance

- vector storage performance

Client CLI Guide

Client CLI Guide

Overview

Installation

Build from Source

Cross-Platform Builds

Quick Start

Commands Reference

Global Flags

health

repos

repos list

repos get

repos add

search

jobs get

JSON Output Format

Success Response

Error Response

Error Codes

Agent Integration

CLAUDE.md Snippet

Example Agent Prompts

Shell Script Examples

Parse JSON with jq

Add Repository and Wait

CI/CD Integration

Configuration

Environment Variables

Configuration Priority

Examples

Common Workflows

Index and Search a New Repository

Monitor Indexing Progress

Batch Search Multiple Repositories

Troubleshooting

Connection Refused

Timeout Errors

Invalid UUID

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally