Command Line Interface

The kit command-line interface provides powerful tools for repository analysis, code exploration, and automation. All major repository operations are available through Unix-friendly commands with multiple output formats.

Installation & Setup

The CLI is automatically available after installing kit:

pip install cased-kit

Verify the installation:

kit --help

Note

The CLI provides the same functionality as the Python API, making it perfect for shell scripts, CI/CD pipelines, and integration with other Unix tools.

Quick Start

# Explore a repository structure
kit file-tree /path/to/your/repo

# Find all Python functions
kit symbols /path/to/your/repo --format names | grep -E "^[a-z_]"

# Search for specific patterns
kit search /path/to/your/repo "TODO" --pattern "*.py"

# Export analysis for external tools
kit export /path/to/your/repo symbols analysis.json

Getting Help

The CLI includes comprehensive built-in help to discover all available commands, arguments, and options:

Main Help

# See all available commands
kit --help

This shows you all the available commands like symbols, search, file-tree, etc.

Command-Specific Help

# Get detailed help for any specific command
kit symbols --help
kit search --help
kit export --help

Each command’s help shows:

• Required arguments (like repository path)
• Optional parameters (like --file, --output, --format)
• Available options (like output formats or filters)
• Short descriptions of what each option does

Example Help Output

$ kit symbols --help

Usage: kit symbols [OPTIONS] PATH

Extract code symbols (functions, classes, etc.) from the repository.

╭─ Arguments ──────────────────────────────────────────╮
│ *  path    TEXT  Path to the local repository.      │
╰──────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────╮
│ --file    -f  TEXT  Extract from specific file only │
│ --output  -o  TEXT  Output to JSON file             │
│ --format      TEXT  Output format: table, json, names │
│ --help            Show this message and exit        │
╰──────────────────────────────────────────────────────╯

Shell Completion

For even faster discovery, install shell completion:

kit --install-completion

After restarting your shell, you can use tab completion to:

• See all available commands: kit <TAB>
• See command options: kit symbols --<TAB>
• Complete file paths: kit symbols /path/to/repo --file src/<TAB>

Command Reference

File Operations

kit file-tree

Get the repository file structure with file sizes and types.

kit file-tree <repository-path> [OPTIONS]

Options:

• --output, -o <file>: Save output to JSON file instead of stdout

Examples:

# Display file tree with icons and sizes
kit file-tree /path/to/repo

# Save to JSON for processing
kit file-tree /path/to/repo --output tree.json

# Pipe to other tools
kit file-tree /path/to/repo | grep "\.py" | head -10

Output:

📄 main.py (1542 bytes)
📄 utils.py (892 bytes)
📁 src
📄 src/core.py (2341 bytes)
📄 src/helpers.py (567 bytes)

kit file-content

Read the content of a specific file within the repository.

kit file-content <repository-path> <file-path>

Examples:

# Read a specific file
kit file-content /path/to/repo src/main.py

# Pipe to other tools
kit file-content /path/to/repo README.md | head -20

kit index

Build a comprehensive index combining file tree and symbols.

kit index <repository-path> [OPTIONS]

Options:

• --output, -o <file>: Save output to JSON file

Examples:

# Generate complete repository index
kit index /path/to/repo --output repo-index.json

# Pipe JSON for analysis
kit index /path/to/repo | jq '.symbols | length'

Symbol Operations

kit symbols

Extract code symbols (functions, classes, variables) from the repository.

kit symbols <repository-path> [OPTIONS]

Options:

• --file, -f <path>: Extract symbols from specific file only
• --output, -o <file>: Save output to JSON file
• --format <format>: Output format (table, json, names)

Examples:

# Table format (default) - human readable
kit symbols /path/to/repo

# JSON format - machine readable
kit symbols /path/to/repo --format json

# Names only - great for piping
kit symbols /path/to/repo --format names

# Specific file analysis
kit symbols /path/to/repo --file src/main.py

# Find only functions
kit symbols /path/to/repo --format names | grep -v "^[A-Z]"

# Count symbols by type
kit symbols /path/to/repo --format json | jq 'group_by(.type) | map({type: .[0].type, count: length})'

Output Formats:

Table Format:

Name                     Type        File                    Lines
------------------------------------------------------------------------
main                     function    src/main.py            10-25
Calculator               class       src/calc.py            5-45
add                      function    src/calc.py            8-12

Names Format:

main
Calculator
add
multiply

kit usages

Find definitions and references of specific symbols across the repository.

kit usages <repository-path> <symbol-name> [OPTIONS]

Options:

• --type, -t <type>: Filter by symbol type (function, class, etc.)
• --output, -o <file>: Save output to JSON file

Examples:

# Find all usages of a symbol
kit usages /path/to/repo "DatabaseConnection"

# Find only class definitions
kit usages /path/to/repo "User" --type class

# Export for analysis
kit usages /path/to/repo "api_call" --output usages.json

Search Operations

kit search

Perform text and regex searches across repository files.

kit search <repository-path> <query> [OPTIONS]

Options:

• --pattern, -p <pattern>: File pattern to search (default: *)
• --output, -o <file>: Save output to JSON file

Examples:

# Search across all files
kit search /path/to/repo "TODO"

# Search only in Python files
kit search /path/to/repo "def main" --pattern "*.py"

# Regex search for function definitions
kit search /path/to/repo "def \w+\(" --pattern "*.py"

# Search in JavaScript files
kit search /path/to/repo "function" --pattern "*.js"

# Case-sensitive search for constants
kit search /path/to/repo "API_KEY"

# Export search results
kit search /path/to/repo "import" --pattern "*.py" --output imports.json

Advanced Search Examples:

# Find all class definitions
kit search /path/to/repo "^class \w+" --pattern "*.py"

# Find SQL queries
kit search /path/to/repo "SELECT.*FROM" --pattern "*.py"

# Find configuration keys
kit search /path/to/repo "\w+_CONFIG" --pattern "*.py"

Context Operations

kit context

Extract surrounding code context for a specific line in a file.

kit context <repository-path> <file-path> <line-number> [OPTIONS]

Options:

• --output, -o <file>: Save output to JSON file

Examples:

# Get context around a specific line
kit context /path/to/repo src/main.py 42

# Export context for analysis
kit context /path/to/repo src/utils.py 15 --output context.json

kit chunk-lines

Split file content into line-based chunks for LLM processing.

kit chunk-lines <repository-path> <file-path> [OPTIONS]

Options:

• --max-lines, -n <count>: Maximum lines per chunk (default: 50)
• --output, -o <file>: Save output to JSON file

Examples:

# Default chunking (50 lines)
kit chunk-lines /path/to/repo src/large-file.py

# Smaller chunks for detailed analysis
kit chunk-lines /path/to/repo src/main.py --max-lines 20

# Export chunks for LLM processing
kit chunk-lines /path/to/repo src/main.py --output chunks.json

kit chunk-symbols

Split file content by code symbols (functions, classes) for semantic chunking.

kit chunk-symbols <repository-path> <file-path> [OPTIONS]

Options:

• --output, -o <file>: Save output to JSON file

Examples:

# Chunk by symbols (functions, classes)
kit chunk-symbols /path/to/repo src/main.py

# Export symbol-based chunks
kit chunk-symbols /path/to/repo src/api.py --output symbol-chunks.json

Export Operations

kit export

Export repository data to structured JSON files for external tools and analysis.

kit export <repository-path> <data-type> <output-file> [OPTIONS]

Data Types:

• index: Complete repository index (files + symbols)
• symbols: All extracted symbols
• file-tree: Repository file structure
• symbol-usages: Usages of a specific symbol

Options:

• --symbol <name>: Symbol name (required for symbol-usages)
• --symbol-type <type>: Symbol type filter (for symbol-usages)

Examples:

# Export complete repository analysis
kit export /path/to/repo index complete-analysis.json

# Export only symbols
kit export /path/to/repo symbols symbols.json

# Export file structure
kit export /path/to/repo file-tree structure.json

# Export symbol usage analysis
kit export /path/to/repo symbol-usages api-usages.json --symbol "ApiClient"

# Export specific symbol type usage
kit export /path/to/repo symbol-usages class-usages.json --symbol "User" --symbol-type class

Server Operations

kit serve

Run the kit REST API server for web integrations and remote access.

kit serve [OPTIONS]

Options:

• --host <host>: Server host (default: 0.0.0.0)
• --port <port>: Server port (default: 8000)
• --reload/--no-reload: Auto-reload on changes (default: True)

Examples:

# Start development server
kit serve

# Production configuration
kit serve --host 127.0.0.1 --port 9000 --no-reload

# Custom port for testing
kit serve --port 3000

PR Review Operations

Note

Want to build a custom PR reviewer? This section covers kit’s production-ready PR reviewer. For a tutorial on building your own custom reviewer using kit’s components, see Build an AI PR Reviewer.

kit review

AI-powered GitHub pull request reviewer that provides comprehensive code analysis with full repository context. The reviewer clones repositories, analyzes symbol relationships, and generates intelligent reviews using Claude or GPT-4.

kit review <pr-url> [OPTIONS]

Options:

• --dry-run: Generate review without posting to GitHub
• --config <file>: Use custom configuration file
• --init-config: Create default configuration file
• --agentic: Use multi-turn agentic analysis (higher cost, deeper analysis)
• --agentic-turns <count>: Number of analysis turns for agentic mode

Examples:

# Review and post comment
kit review https://github.com/owner/repo/pull/123

# Dry run (generate review without posting)
kit review --dry-run https://github.com/owner/repo/pull/123

# Use agentic mode for complex PRs
kit review --agentic --agentic-turns 15 https://github.com/owner/repo/pull/123

# Initialize configuration
kit review --init-config

Quick Setup

1. Install and configure:

# Install kit
pip install cased-kit

# Set up configuration
kit review --init-config

# Set API keys
export KIT_GITHUB_TOKEN="ghp_your_token"
export KIT_ANTHROPIC_TOKEN="sk-ant-your_key"

2. Review a PR:

kit review https://github.com/owner/repo/pull/123

Configuration

The reviewer uses ~/.kit/review-config.yaml for configuration:

github:
  token: ghp_your_token_here
  base_url: https://api.github.com

llm:
  provider: anthropic  # or "openai"
  model: claude-sonnet-4-20250514
  api_key: sk-ant-your_key_here
  max_tokens: 4000
  temperature: 0.1

review:
  analysis_depth: standard  # quick, standard, thorough
  post_as_comment: true
  clone_for_analysis: true
  cache_repos: true
  cache_directory: ~/.kit/repo-cache
  cache_ttl_hours: 24

Model Selection

Frontier Tier ($15-75/MTok)

• claude-opus-4-20250514: Latest flagship, world’s best coding model, superior complex reasoning
• claude-sonnet-4-20250514: High-performance with exceptional reasoning and efficiency

Premium Tier ($3-15/MTok)

• claude-3-7-sonnet-20250219: Extended thinking capabilities
• claude-3-5-sonnet-20241022: Proven excellent balance

Balanced Tier ($0.80-4/MTok)

• gpt-4o-mini-2024-07-18: Excellent value model
• claude-3-5-haiku-20241022: Fastest responses

Cache Management

# Check cache status
kit review-cache status

# Clean up old repositories
kit review-cache cleanup

# Clear all cached repositories
kit review-cache clear

Enterprise Usage

Batch Review:

# Review multiple PRs
for pr in 123 124 125; do
  kit review https://github.com/company/repo/pull/$pr
done

CI/CD Integration:

.github/workflows/pr-review.yml

name: AI PR Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - name: AI Review
        run: |
          pip install cased-kit
          kit review --dry-run ${{ github.event.pull_request.html_url }}
        env:
          KIT_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          KIT_ANTHROPIC_TOKEN: ${{ secrets.ANTHROPIC_API_KEY }}

Cost Analysis

Real-world costs by team size:

Small Team (20 PRs/month):

• Standard mode: $0.20-1.00/month
• Mixed usage: $1.00-5.00/month

Enterprise (500 PRs/month):

• Standard mode: $5.00-25.00/month
• Mixed usage: $25.00-150.00/month

Cost per PR by complexity:

• Simple (1-2 files): $0.005-0.025
• Medium (3-5 files): $0.01-0.05
• Complex (6+ files): $0.025-0.10

Features

Intelligent Analysis:

• Repository cloning with caching for 5-10x faster repeat reviews
• Symbol extraction and cross-codebase impact analysis
• Security, architecture, and performance assessment
• Multi-language support for any language kit supports

Cost Transparency:

• Real-time cost tracking with exact LLM usage
• Token breakdown (input/output) for cost optimization
• Model information and pricing details

Enterprise Features:

• GitHub integration with classic and fine-grained tokens
• Multiple LLM provider support (Anthropic Claude, OpenAI GPT-4)
• Configurable analysis depth and review modes
• Repository caching and batch operations

Example Output

## 🛠️ Kit AI Code Review

### Summary & Implementation
This PR introduces a new authentication middleware that validates JWT tokens...

### Code Quality Assessment
The implementation follows clean code principles with appropriate error handling...

### Cross-Codebase Impact Analysis
- **AuthMiddleware**: Used in 15 other places across the codebase
- **validateToken**: New function will be called by 8 existing routes
- Breaking change risk: Low (additive changes only)

### Security & Reliability
✅ Proper JWT validation with signature verification
⚠️ Consider adding rate limiting for failed authentication attempts

### Specific Issues & Recommendations
1. **Line 42 in auth.py**: Consider using constant-time comparison
2. **Line 67 in middleware.py**: Add input validation for token format

---
*Generated by kit v0.3.3 with claude-sonnet-4 analysis*

Output Formats

Human-Readable Formats

• Table: Structured columns for easy reading
• Plain Text: Simple text output for basic parsing
• Icons: File type indicators (📄 for files, 📁 for directories)

Machine-Readable Formats

• JSON: Structured data perfect for further processing
• Names: Simple lists for Unix pipeline operations

Piping & Integration

All commands work seamlessly with Unix tools:

# Count Python files
kit file-tree /path/to/repo | grep "\.py" | wc -l

# Find large functions (over 50 lines)
kit symbols /path/to/repo --format json | jq '.[] | select(.end_line - .start_line > 50)'

# Get unique function names
kit symbols /path/to/repo --format names | sort | uniq

# Find files with many symbols
kit symbols /path/to/repo --format json | jq -r '.[] | .file' | sort | uniq -c | sort -nr

Practical Workflows

Code Review Preparation

#!/bin/bash
REPO_PATH="/path/to/repo"
OUTPUT_DIR="./analysis"

mkdir -p $OUTPUT_DIR

# Generate comprehensive analysis
kit export $REPO_PATH index $OUTPUT_DIR/repo-index.json

# Find all TODO items
kit search $REPO_PATH "TODO\|FIXME\|HACK" > $OUTPUT_DIR/todos.txt

# Analyze function complexity (functions over 30 lines)
kit symbols $REPO_PATH --format json | \
  jq '.[] | select(.type=="function" and (.end_line - .start_line) > 30)' \
  > $OUTPUT_DIR/complex-functions.json

echo "Analysis complete in $OUTPUT_DIR/"

Documentation Generation

#!/bin/bash
REPO_PATH="/path/to/repo"
DOCS_DIR="./docs"

mkdir -p $DOCS_DIR

# Extract all public APIs
kit symbols $REPO_PATH --format json | \
  jq '.[] | select(.type=="function" and (.name | startswith("_") | not))' \
  > $DOCS_DIR/public-api.json

# Generate symbol usage reports
for symbol in $(kit symbols $REPO_PATH --format names | head -10); do
  kit usages $REPO_PATH "$symbol" --output "$DOCS_DIR/usage-$symbol.json"
done

Migration Analysis

#!/bin/bash
OLD_REPO="/path/to/old/repo"
NEW_REPO="/path/to/new/repo"

# Compare symbol counts
echo "Old repo symbols:"
kit symbols $OLD_REPO --format names | wc -l

echo "New repo symbols:"
kit symbols $NEW_REPO --format names | wc -l

# Find deprecated patterns
kit search $OLD_REPO "deprecated\|legacy" --pattern "*.py" > deprecated-code.txt

# Export both for detailed comparison
kit export $OLD_REPO symbols old-symbols.json
kit export $NEW_REPO symbols new-symbols.json

CI/CD Integration

.github/workflows/code-analysis.yml

name: Code Analysis
on: [push, pull_request]

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Install kit
        run: pip install cased-kit

      - name: Analyze codebase
        run: |
          # Generate repository analysis
          kit export . index analysis.json

          # Check for complexity issues
          COMPLEX_FUNCTIONS=$(kit symbols . --format json | jq '[.[] | select(.type=="function" and (.end_line - .start_line) > 50)] | length')

          if [ $COMPLEX_FUNCTIONS -gt 10 ]; then
            echo "Warning: $COMPLEX_FUNCTIONS functions are longer than 50 lines"
          fi

          # Find security-related patterns
          kit search . "password\|secret\|key" --pattern "*.py" > security-review.txt

      - name: Upload analysis
        uses: actions/upload-artifact@v3
        with:
          name: code-analysis
          path: |
            analysis.json
            security-review.txt

Best Practices

Performance

• Use --format names for large repositories when you only need symbol names
• Leverage file patterns (--pattern) to limit search scope
• Export to JSON once, then use jq for multiple queries

Scripting

• Always check command exit codes ($?) in scripts
• Use --output to save data persistently rather than relying on stdout capture
• Combine with jq, grep, sort, and other Unix tools for powerful analysis

Integration

• Export JSON data for integration with external tools and databases
• Use the CLI in CI/CD pipelines for automated code quality checks
• Combine with language servers and IDEs for enhanced development workflows