GitHub Copilot CLI Tool

A powerful command-line interface for GitHub Copilot that provides programming assistance directly from your terminal.

🚀 Features

• Direct GitHub Copilot Integration: Seamlessly connects to GitHub Copilot APIs
• Intelligent Token Caching: Disk-based caching for lightning-fast subsequent requests
• Syntax Highlighting: Beautiful code formatting with language-specific highlighting
• Multiple AI Models: Support for GPT-4, GPT-3.5-turbo, Claude-3, and more
• Configurable Parameters: Control temperature, token limits, and output verbosity
• Robust Error Handling: Clear error messages with actionable guidance
• Environment Variables: Flexible configuration through environment variables
• Test-Driven Development: Comprehensive test coverage following TDD principles

📦 Installation

Prerequisites

• Go 1.21 or later
• Active GitHub Copilot subscription
• GitHub CLI installed and authenticated

Build from Source

git clone https://github.com/user/copilot-cli.git
cd copilot-cli
go build -o copilot-cli .

Install to PATH

# Linux/macOS
sudo cp copilot-cli /usr/local/bin/

# Or add to your PATH
export PATH=$PATH:$(pwd)

🛠️ Setup

1. Ensure GitHub Copilot is authenticated:

   gh auth login

2. Verify Copilot configuration exists:

   ls ~/.config/github-copilot/apps.json

3. Test the installation:

   copilot-cli --help

📖 Usage

Basic Usage

# Simple query
copilot-cli "how to merge PDF files starting with ab_"

# Multi-word queries (quotes optional)
copilot-cli implement binary search in golang

Advanced Usage

# Use specific model
copilot-cli --model gpt-3.5-turbo "read csv file in python"

# Verbose output with usage statistics
copilot-cli --verbose "optimize database query"

# Custom parameters
copilot-cli --temperature 0.5 --max-tokens 2000 "complex algorithm question"

# Custom configuration path
copilot-cli --config /custom/path "programming question"

Environment Variables

# Set default model
export COPILOT_MODEL="gpt-4"

# Set custom config path
export COPILOT_CONFIG="/custom/copilot/config"

# Enable verbose by default
export COPILOT_VERBOSE="true"

# Enable debug logging for troubleshooting
export COPILOT_DEBUG="1"

# Now use without flags
copilot-cli "your question"

🎯 Examples

Example 1: PDF File Merging

$ copilot-cli "how to merge all pdf files into one which starts with ab_"

Output:

To merge PDF files starting with 'ab_', you can use Python with PyPDF2:

┌─ python
│ import os
│ from PyPDF2 import PdfMerger
│ 
│ merger = PdfMerger()
│ 
│ # Find all PDF files starting with 'ab_'
│ for filename in os.listdir('.'):
│     if filename.startswith('ab_') and filename.endswith('.pdf'):
│         merger.append(filename)
│ 
│ # Write merged PDF
│ with open('merged_ab_files.pdf', 'wb') as output_file:
│     merger.write(output_file)
│ 
│ print('PDFs merged successfully!')
└─

Example 2: Database Optimization

$ copilot-cli --verbose "optimize slow database query"

Output:

Here are key strategies to optimize slow database queries:

1. **Add Indexes**: Create indexes on columns used in WHERE, JOIN, and ORDER BY
2. **Query Analysis**: Use EXPLAIN to understand query execution plans
3. **Avoid SELECT ***: Only select needed columns
4. **Optimize JOINs**: Ensure proper join conditions and consider join order

┌─ sql
│ -- Add index example
│ CREATE INDEX idx_user_email ON users(email);
│ 
│ -- Analyze query performance
│ EXPLAIN SELECT * FROM users WHERE email = 'user@example.com';
└─

─────────────────────────────────────────────────
📊 Token usage: 15 prompt + 120 completion = 135 total
🤖 Model: gpt-4
✅ Completion reason: stop

Example 3: Multiple Models

# Compare responses from different models
copilot-cli --model gpt-4 "implement quicksort"
copilot-cli --model gpt-3.5-turbo "implement quicksort"

⚡ Performance & Caching

Intelligent Token Caching

The CLI implements disk-based token caching for optimal performance:

• First Run: Authenticates with GitHub API and caches token to ~/.cache/llm-cli/token.json
• Subsequent Runs: Loads token from disk cache - dramatically faster startup
• Automatic Expiration: Expired tokens are automatically detected and refreshed
• Security: Cache files use 0600 permissions (owner read/write only)

Performance Benefits

# First execution (cold start)
$ time copilot-cli "help me code"
# → API authentication + caching
# → real    0m2.1s

# Subsequent executions (warm start)
$ time copilot-cli "write a function"  
# → Load from cache
# → real    0m0.3s  ← 85% faster!

Cache Management

# View cache status
ls -la ~/.cache/llm-cli/

# Clear cache manually if needed
rm ~/.cache/llm-cli/token.json

# Cache is automatically managed:
# - Expired tokens are removed
# - Corrupted cache files are cleaned up
# - Thread-safe concurrent access

⚙️ Configuration

Command-Line Flags

Flag	Short	Default	Description
--model	-m	gpt-4	AI model to use
--verbose	-v	false	Enable verbose output
--temperature	-t	0.1	Response randomness (0.0-1.0)
--max-tokens		1000	Maximum response tokens
--config		~/.config/github-copilot	Config directory path
--help	-h		Show help message

Supported Models

• gpt-4 - Most capable, best for complex problems
• gpt-3.5-turbo - Faster, good for simpler tasks
• claude-3 - Alternative model with different strengths
• claude-3-sonnet - Balanced performance and speed
• claude-3-haiku - Fastest responses

Environment Variables

Variable	Description	Example
COPILOT_MODEL	Default model	gpt-4
COPILOT_CONFIG	Config directory	/custom/path
COPILOT_TEMPERATURE	Default temperature	0.5
COPILOT_MAX_TOKENS	Default max tokens	2000
COPILOT_VERBOSE	Enable verbose mode	true
COPILOT_DEBUG	Enable debug logging	1

🏗️ Architecture

The application follows a clean, modular architecture designed for maintainability and extensibility:

copilot-cli/
├── main.go                 # Entry point and application orchestration
├── internal/models/        # Core data structures and validation
├── pkg/auth/              # GitHub authentication and token management
├── pkg/client/            # HTTP client and API integration
├── pkg/cli/               # Command-line interface and argument parsing
├── pkg/formatter/         # Response formatting and terminal output
├── testdata/              # Test fixtures and mock data
└── docs/                  # Architecture and API documentation

Key Components

• Authentication (pkg/auth): Manages GitHub OAuth tokens and Copilot API access with intelligent disk caching
• HTTP Client (pkg/client): Handles API communication with retry logic and error handling
• CLI Parser (pkg/cli): Processes command-line arguments and builds requests
• Formatter (pkg/formatter): Renders responses with syntax highlighting and formatting
• Models (internal/models): Defines data structures and validation logic

Token Caching Architecture

Authentication Flow:
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Memory Cache  │ -> │   Disk Cache     │ -> │  GitHub API     │
│   (Runtime)     │    │ ~/.cache/llm-cli │    │ (api.github.com)│
└─────────────────┘    └──────────────────┘    └─────────────────┘
     ↑ Fastest              ↑ Fast                    ↑ Slowest
     
Cache Lifecycle:
1. Check memory cache (immediate)
2. Check disk cache (fast file read)
3. Fetch from API + cache to disk and memory
4. Automatic cleanup of expired tokens

🧪 Development

Prerequisites

• Go 1.21+
• GitHub Copilot access
• Git

Setup Development Environment

# Clone repository
git clone https://github.com/user/copilot-cli.git
cd copilot-cli

# Install dependencies
go mod tidy

# Run tests
go test ./...

# Run with coverage
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

Test-Driven Development

This project was built following strict TDD principles:

1. Red: Write failing tests that describe desired behavior
2. Green: Implement minimal code to make tests pass
3. Refactor: Improve code quality while keeping tests green

Running Tests

# Run all tests
go test ./...

# Run tests with verbose output
go test -v ./...

# Run specific package tests
go test ./pkg/auth -v
go test ./pkg/client -v
go test ./pkg/cli -v

# Run tests with coverage
go test -cover ./...

# Benchmark tests
go test -bench=. ./...

Project Structure

copilot-cli/
├── main.go                     # Application entry point
├── go.mod                      # Go module definition
├── go.sum                      # Dependency checksums
├── README.md                   # This file
├── internal/                   # Private packages
│   ├── models/                 # Core data structures
│   │   ├── models.go          
│   │   └── models_test.go
│   └── config/                 # Configuration management
├── pkg/                        # Public packages
│   ├── auth/                   # Authentication
│   │   ├── auth.go
│   │   └── auth_test.go
│   ├── client/                 # HTTP client
│   │   ├── client.go
│   │   └── client_test.go
│   ├── cli/                    # CLI interface
│   │   ├── cli.go
│   │   └── cli_test.go
│   └── formatter/              # Response formatting
│       ├── formatter.go
│       └── formatter_test.go
├── testdata/                   # Test fixtures
│   ├── sample_apps.json
│   └── mock_responses.json
└── docs/                       # Documentation
    ├── ARCHITECTURE.md
    ├── API.md
    └── CONTRIBUTING.md

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Workflow

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature
3. Write tests first (TDD approach)
4. Implement your feature
5. Ensure all tests pass: go test ./...
6. Commit your changes: git commit -am 'Add some feature'
7. Push to the branch: git push origin feature/your-feature
8. Submit a pull request

Code Quality

• Follow Go best practices and conventions
• Write comprehensive tests for all new code
• Ensure test coverage remains above 80%
• Document all public APIs with godoc comments
• Run go fmt and go vet before committing

🔍 Troubleshooting

Authentication Issues

Problem: Authentication Error: invalid or expired credentials

Solutions:

1. Re-authenticate with GitHub CLI: gh auth login
2. Verify Copilot subscription is active
3. Check that ~/.config/github-copilot/apps.json exists and is valid

Configuration Issues

Problem: Configuration Error: github copilot configuration not found

Solutions:

1. Install GitHub Copilot CLI: gh extension install github/gh-copilot
2. Authenticate: gh copilot auth
3. Verify config file: cat ~/.config/github-copilot/apps.json

Network Issues

Problem: Network Error: network request failed

Solutions:

1. Check internet connection
2. Verify GitHub API accessibility: curl -I https://api.github.com
3. Check for proxy or firewall issues
4. Try again after a few moments

Rate Limiting

Problem: Rate Limit Error: API rate limit exceeded

Solutions:

1. Wait before making another request
2. Consider upgrading your Copilot plan for higher limits
3. Use the --verbose flag to monitor token usage

Cache Issues

Problem: CLI seems slow despite caching

Solutions:

1. Check cache directory exists: ls -la ~/.cache/llm-cli/
2. Verify cache file permissions: should be 600 (owner only)
3. Check cache file content: cat ~/.cache/llm-cli/token.json
4. Clear corrupted cache: rm ~/.cache/llm-cli/token.json

Problem: Permission denied accessing cache

Solutions:

1. Check directory permissions: ls -ld ~/.cache/llm-cli/
2. Fix permissions: chmod 700 ~/.cache/llm-cli/
3. Ensure you own the directory: ls -la ~/.cache/

Cache Location: ~/.cache/llm-cli/token.json

• Automatic Management: Expired tokens cleaned up automatically
• Security: Files created with 600 permissions
• Thread-Safe: Concurrent access properly handled

📝 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• GitHub Copilot team for the amazing AI assistance platform
• Go community for excellent tooling and libraries
• Contributors and testers who help improve this tool

🔗 Links

• GitHub Repository
• Issue Tracker
• GitHub Copilot Documentation
• Go Documentation

---

Made with ❤️ for developers who love the command line