🔍 Research CLI

AI-powered research assistant with web search capabilities
Transform any question into comprehensive research in seconds.

✨ What Makes This Special

Research CLI is a zero-install TypeScript CLI tool that brings the power of multiple AI providers to your terminal with beautiful, professional output and secure credential management.

🎯 Perfect For

• Developers researching APIs, frameworks, and best practices
• Researchers gathering information with citations and sources
• Content creators exploring topics with web-enhanced AI responses
• Students getting quick explanations with optional deep-dives
• Teams standardizing research workflows with shared configurations

🚀 Quick Start

Option 1: Interactive Setup (Recommended for New Users)

npx research-cli easymode

Guides you through provider selection, API key setup, and your first query!

Option 2: Direct Usage (For Quick Queries)

# Basic research
npx research-cli "What are the latest developments in quantum computing?"

# With web search
npx research-cli "TypeScript 5.0 new features" --web

# Specific provider and model
npx research-cli "Explain React hooks" --provider openai --model gpt-4o

🎨 Beautiful Terminal Experience

Professional Output Formatting

research-cli "Explain GraphQL" --web

Features beautiful colored output with:

• 🎨 Semantic Color Themes - Provider-specific branding
• 📊 Real-time Progress Bars - Visual feedback during API calls
• 🔍 Web Search Indicators - See when tools are being used
• ⚡ Streaming Responses - Watch results appear in real-time

Interactive Setup Flow

research-cli easymode

Beautiful guided setup with:

• 🎯 Provider Selection Menu - Choose from OpenAI, Claude, Perplexity, Gemini
• 🔐 Secure Key Entry - Masked input with format validation
• 🧪 Connection Testing - Automatic API key validation
• 🚀 Quick Demo - Try your first query immediately

🛠 Comprehensive Features

🤖 Multi-Provider AI Support

• OpenAI - GPT-4, GPT-4o, o3 models
• Anthropic Claude - Claude 3.5 Sonnet, Haiku models
• Perplexity - Research-focused with built-in web search
• Google Gemini - Gemini Pro, Ultra models

🔐 Enterprise-Grade Security

• Secure Storage - API keys stored in system keychain (macOS, Windows, Linux)
• Environment Support - Respects OPENAI_API_KEY, CLAUDE_API_KEY, etc.
• Never Logged - Credentials redacted in dry-run mode
• Migration Tools - Safely move from config files to secure storage

📊 Multiple Output Formats

• Markdown (--format md) - Beautiful terminal rendering (default)
• JSON (--format json) - Structured data for automation
• JSONL (--format jsonl) - Event stream for real-time processing
• Raw (--format raw) - Plain text for simple integration

🌐 Web Search Integration

# Enable web search for current information
research-cli "Latest AI research papers 2024" --web

# Control search depth
research-cli "Stock market today" --web --web-search-context-size high

⚙️ Flexible Configuration

# Save preferences
research-cli config set defaultProvider openai
research-cli config set defaultModel gpt-4o

# View current config
research-cli config show

# Reset to defaults
research-cli config reset

📚 Complete Command Reference

🔍 Research Commands

# Basic usage (default command)
research-cli "your question here"
research-cli research "your question here"  # explicit

# Research options
research-cli "question" \
  --provider openai \           # openai, claude, perplexity, gemini
  --model gpt-4o \             # provider-specific models
  --web \                      # enable web search
  --format json \              # md, json, jsonl, raw
  --output results.md \        # save to file
  --temperature 0.7 \          # generation creativity
  --max-tokens 1000 \          # response length limit
  --verbose                    # detailed logging

🎯 Setup & Onboarding

research-cli easymode                    # Interactive guided setup
research-cli easymode --provider openai  # Skip provider selection
research-cli setup                       # Alternative command name
research-cli easy                        # Short alias

🔐 Authentication Management

# Setup and login
research-cli auth login openai           # Interactive API key setup
research-cli auth login openai --key sk-... # Direct key provision

# Status and testing
research-cli auth list                   # Show all configured providers
research-cli auth status                 # Legacy status command
research-cli auth test openai           # Test specific provider
research-cli auth keyring-status         # Check system keyring

# Key management
research-cli auth logout openai          # Remove API key
research-cli auth logout openai --force  # Skip confirmation
research-cli auth migrate                # Move from config to keyring

⚙️ Configuration

# Configuration management
research-cli config init                 # Create default config
research-cli config show                 # Display current settings
research-cli config get defaultProvider  # Get specific value
research-cli config set theme dark       # Set configuration value
research-cli config reset                # Reset to defaults
research-cli config reset --force        # Skip confirmation

🛠 Utility & Debug

# Debug and development
research-cli "test query" --dry-run      # Preview request payload
research-cli "question" --verbose        # Detailed execution logging
research-cli --version                   # Show version info
research-cli --help                      # Comprehensive help

🏗 Advanced Usage Patterns

🔄 Automation & Scripting

# Batch processing with JSONL output
echo "Question 1\nQuestion 2\nQuestion 3" | \
while read question; do
  research-cli "$question" --format jsonl >> results.jsonl
done

# CI/CD integration
OPENAI_API_KEY=$SECRET research-cli \
  "Analyze this codebase for security issues" \
  --format json \
  --output security-report.json

🎨 Custom Workflows

# Research pipeline with web search
research-cli "Latest React patterns 2024" --web --format json | \
  jq '.content' | \
  research-cli "Summarize this in 3 bullet points" --format md

🔧 Development Integration

# IDE integration (VS Code task)
{
  "label": "Research Topic",
  "type": "shell",
  "command": "research-cli",
  "args": ["${input:topic}", "--web", "--format", "md"],
  "group": "build"
}

🧠 Smart Features

🎯 Progressive Disclosure Design

• Beginners: Start with easymode for guided setup
• Intermediate: Use basic commands with helpful defaults
• Advanced: Access full option set for complex workflows

🔍 Intelligent Defaults

• Auto-detect best provider based on query type
• Smart formatting based on output destination (TTY vs file)
• Context-aware web search activation
• Graceful fallbacks when providers are unavailable

📱 Cross-Platform Excellence

• macOS: Native keychain integration
• Windows: Windows Credential Store support
• Linux: Secret Service API compatibility
• CI/CD: Environment variable fallbacks

🛡 Security & Privacy

🔐 Credential Security

• ✅ Never stored in plaintext - System keychain only
• ✅ Automatic redaction - Sensitive data masked in logs
• ✅ Secure transmission - HTTPS/TLS for all API calls
• ✅ Local processing - No data sent to third parties

🔒 Best Practices

• API keys stored using native OS credential managers
• Environment variables supported for ephemeral use
• Dry-run mode for testing without API calls
• Comprehensive error handling with specific error codes

🚀 Installation & Setup

System Requirements

• Node.js 20+ (required for stable fetch and stream APIs)
• TypeScript (included in dependencies)
• System keychain (macOS Keychain, Windows Credential Store, Linux Secret Service)

Installation Options

Option 1: Direct Usage (Recommended)

npx research-cli easymode

Zero installation required - downloads and runs latest version.

Option 2: Global Installation

npm install -g research-cli
research-cli easymode

Option 3: Local Development

git clone https://github.com/your-username/research-cli.git
cd research-cli
pnpm install
pnpm build
pnpm dev "your question here"

First-Time Setup

1. Run easymode: research-cli easymode
2. Choose provider: OpenAI, Claude, Perplexity, or Gemini
3. Add API key: Securely stored in system keychain
4. Test connection: Automatic validation
5. Start researching: You're ready to go!

🔧 Development

Tech Stack

• TypeScript - Strict mode, ESM modules
• Clipanion - Modern CLI framework with decorators
• Chalk - Terminal styling and semantic colors
• terminal-kit - Interactive prompts and progress
• keytar - Cross-platform credential storage
• Biome - Code formatting and linting

Development Commands

# Development
pnpm dev "test query"        # Run with ts-node
pnpm build                   # Compile TypeScript
pnpm clean                   # Remove dist/

# Quality assurance
pnpm typecheck              # TypeScript checking
pnpm lint                   # ESLint + Biome
pnpm biome check --write    # Format and fix

# Testing
pnpm test                   # Run test suite
node dist/cli.js --dry-run  # Manual testing

Project Structure

src/
├── cli.ts                  # Clipanion CLI entry point
├── types.ts               # Core TypeScript interfaces
├── auth/
│   └── keyring-manager.ts # Secure credential storage
├── commands/
│   ├── auth.ts           # Authentication commands
│   ├── config.ts         # Configuration management
│   ├── easymode.ts       # Interactive setup
│   ├── query.ts          # Core research logic
│   └── research.ts       # Main research command
├── providers/
│   └── openai.ts         # OpenAI API integration
├── render/
│   └── markdown.ts       # Terminal output formatting
├── ui/
│   ├── styles.ts         # Chalk color system
│   ├── formatters.ts     # Message formatting
│   ├── progress.ts       # Progress bar management
│   ├── interactive.ts    # Terminal-kit prompts
│   └── boxes.ts          # Layout components
└── utils/
    └── credentials.ts    # API key utilities

🎓 Examples & Tutorials

Academic Research

# Literature review with citations
research-cli "Recent advances in machine learning 2024" \
  --web \
  --web-search-context-size high \
  --output literature-review.md

# Technical deep-dive
research-cli "Explain transformer architecture in detail" \
  --provider claude \
  --model claude-3-5-sonnet \
  --max-tokens 2000

Development Workflow

# API documentation research
research-cli "How to use React Server Components" --web

# Framework comparison
research-cli "Next.js vs Nuxt.js vs SvelteKit comparison 2024" \
  --format json \
  --output framework-comparison.json

# Debugging assistance
research-cli "Why is my TypeScript build failing with module resolution error?" \
  --provider openai \
  --temperature 0.1

Content Creation

# Blog post research
research-cli "Latest trends in web development 2024" \
  --web \
  --format md \
  --output blog-research.md

# Social media content
research-cli "Create engaging tweet about AI developments" \
  --max-tokens 280 \
  --temperature 0.8

🐛 Troubleshooting

Common Issues

API Key Problems

# Check API key status
research-cli auth list

# Test specific provider
research-cli auth test openai

# Re-setup provider
research-cli auth logout openai
research-cli auth login openai

Connection Issues

# Verbose logging for debugging
research-cli "test query" --verbose

# Test with dry-run (no API call)
research-cli "test query" --dry-run

# Check keyring status
research-cli auth keyring-status

Configuration Problems

# Reset configuration
research-cli config reset --force

# Reinitialize
research-cli config init

# Manual configuration check
cat ~/.config/research-cli/config.json

Error Codes

• PROVIDER_TIMEOUT - API request timeout
• API_KEY_MISSING - No API key found
• INVALID_PROVIDER - Unsupported provider specified
• KEYRING_UNAVAILABLE - System keychain access failed
• CONFIG_PARSE_ERROR - Configuration file corruption

📊 Comparison

vs. ChatGPT Web Interface

✅ Terminal-native - No browser switching
✅ Scriptable - Automation and CI/CD integration
✅ Multiple providers - Not locked to one service
✅ Local storage - Your data stays on your machine

vs. curl + API

✅ User-friendly - No JSON payload construction
✅ Secure credentials - Automatic key management
✅ Beautiful output - Formatted for humans
✅ Error handling - Meaningful error messages

vs. Other CLI Tools

✅ Multi-provider - OpenAI, Claude, Perplexity, Gemini
✅ Web search - Enhanced with real-time information
✅ Professional UI - Progress bars, colors, interactivity
✅ TypeScript native - Type-safe from the ground up

🗺 Roadmap

🚧 Coming Soon

• [ ] Plugin System - Custom providers and formatters
• [ ] Template Engine - Reusable prompt templates
• [ ] Conversation Mode - Multi-turn research sessions
• [ ] File Input - Research documents and codebases
• [ ] Export Formats - PDF, DOCX, HTML output

🔮 Future Ideas

• [ ] Voice Input - Speech-to-text research queries
• [ ] Visual Output - Charts and graphs generation
• [ ] Collaboration - Shared research sessions
• [ ] Analytics - Usage metrics and insights
• [ ] Mobile App - iOS/Android companion

🤝 Contributing

We welcome contributions! Here's how to get started:

🐛 Bug Reports

• Use the issue template
• Include command that failed
• Attach error output (with credentials redacted)
• Specify your OS and Node.js version

✨ Feature Requests

• Describe the use case
• Explain the expected behavior
• Consider backward compatibility
• Provide implementation ideas if possible

🔧 Development Contributions

1. Fork the repository
2. Create feature branch: git checkout -b feature/amazing-feature
3. Follow code style: Run pnpm biome check --write
4. Add tests: Ensure new features are tested
5. Update docs: Keep README and help text current
6. Submit PR: Include detailed description

🙏 Acknowledgments

Technologies That Made This Possible

• Clipanion - Elegant CLI framework
• Chalk - Terminal styling
• terminal-kit - Interactive components
• keytar - Secure credential storage
• OpenAI - GPT models and API
• Anthropic - Claude models
• Perplexity - Research-focused AI

Inspiration

• GitHub CLI - Excellence in CLI design
• Vercel CLI - Developer experience focus
• Stripe CLI - Professional API tooling

📄 License

MIT License - Feel free to use this in your personal and commercial projects.

See LICENSE for full details.

Made with ❤️ for developers, researchers, and curious minds everywhere

⭐ Star this repo • 🐛 Report bugs • 💡 Request features