manx-cli 0.3.3

A blazing-fast CLI documentation finder powered by Context7 MCP
manx-cli-0.3.3 is not a library.
Visit the last successful build: manx-cli-0.5.9

📚 Manx

A blazing-fast CLI documentation finder that brings Context7 MCP docs right to your terminal - no IDE required

License Language Status Binary Size

What is Manx?

Manx is a command-line interface documentation finder designed for developers who prefer working in the terminal. It uses Context7 MCP (Model Context Protocol) as its primary backend to provide real-time, version-specific documentation snippets without leaving your development environment.

Why Manx?

  • ⚡ < 1 second search results
  • 🎯 Version-specific docs (e.g., React 18 vs 17)
  • 📦 Single 2.9MB binary - no dependencies
  • 🔌 Context7 MCP integration - always up-to-date
  • 💾 Smart caching - works offline after first use
  • 🌈 Beautiful terminal output with syntax highlighting
  • 📊 Smart result limiting - shows 10 results by default, customizable
  • 🚀 Export to Markdown/JSON for documentation

Quick Install

# Linux/macOS - Install to /usr/local/bin
curl -fsSL https://raw.githubusercontent.com/neur0map/manx/main/install.sh | bash

# Or with wget
wget -qO- https://raw.githubusercontent.com/neur0map/manx/main/install.sh | bash

Quick Start

# Search for any library
manx fastapi

# Search with a query
manx fastapi middleware

# Version-specific search  
manx react@18 hooks

# Get full documentation
manx doc fastapi authentication

# Limit results (default: 10, use 0 for unlimited)
manx fastapi --limit 5
manx react hooks --limit 0

# Save results to file
manx fastapi --save 1,3,5
manx react hooks --save-all --json

Manual Installation

  1. Download the latest release for your platform:

  2. Make executable and move to PATH:

    chmod +x manx-*
sudo mv manx-* /usr/local/bin/manx

  3. Verify installation:

    manx --version

From Source (Cargo)

# Install from crates.io (coming soon)
cargo install manx

# Or build from source
git clone https://github.com/neur0map/manx.git
cd manx
cargo build --release
sudo cp target/release/manx /usr/local/bin/

Basic Search

manx <library>              # Search library docs
manx <library> <query>      # Search library for specific query
manx <library>@<version>    # Version-specific search

# Examples
manx fastapi                # All FastAPI docs
manx fastapi cors           # FastAPI CORS documentation  
manx react@18              # React v18 documentation
manx vue@3 composition     # Vue 3 Composition API

Full Documentation

manx doc <library> <query>  # Get comprehensive documentation

# Examples  
manx doc fastapi middleware    # Complete FastAPI middleware guide
manx doc react hooks          # Full React Hooks documentation
manx doc django orm           # Django ORM complete guide

Result Limiting

manx fastapi --limit 5         # Show only first 5 results
manx react hooks --limit 0     # Show all results (unlimited)
manx vue --limit 15            # Show first 15 results
# Default limit is 10 results

Export Options

manx fastapi --save 1,3,7     # Save specific results as markdown
manx fastapi --save 1,3,7 --json  # Save as JSON
manx react --save-all         # Save all results
manx doc react -o react.md    # Export documentation

Cache Management

manx cache stats           # Show cache statistics
manx cache list            # List cached libraries
manx cache clear           # Clear all cached data
manx --clear-cache         # Quick cache clear (global flag)

Other Options

manx --limit 5                 # Limit number of results (default: 10)
manx --offline                 # Use cache only (no network)
manx --quiet                   # JSON output (for scripts)
manx --debug                   # Enable debug logging

Important: Without an API key, Manx uses Context7's shared MCP endpoint which has strict rate limits. Users often experience rate limiting after just a few searches. Setting up an API key provides dedicated access with much higher limits.

Why You Need an API Key

  • Without API Key: Uses shared MCP endpoint (mcp.context7.com/mcp) with very low rate limits
  • With API Key: Uses dedicated API endpoint with high rate limits
  • ✅ Faster responses and better reliability
  • ✅ Premium features access

Getting Your API Key

  1. Visit the Context7 Dashboard
  2. Create a free account or log in
  3. Generate your API key (starts with sk-)
  4. Set it up in manx:
# Method 1: Using config command (recommended)
manx config --api-key sk-your-context7-key-here

# Method 2: Environment variable
export MANX_API_KEY=sk-your-context7-key-here

# Method 3: Direct config file edit (~/.config/manx/config.json)
{
  "api_key": "sk-your-context7-key-here"
}

Verifying Your Setup

# Check current configuration
manx config --show

# Test with your API key (should be much faster)
manx fastapi

Removing Your API Key

# Remove API key (switches back to shared rate limits)
manx config --api-key ""

# Or unset environment variable
unset MANX_API_KEY

Note: The API key only affects rate limiting and endpoint selection. All documentation content remains the same.

Manx stores configuration in ~/.config/manx/config.json:

{
  "api_key": "sk-your-context7-key",
  "cache_dir": null,
  "default_limit": 10,
  "offline_mode": false,
  "color_output": true,
  "auto_cache_enabled": true,
  "cache_ttl_hours": 24,
  "max_cache_size_mb": 100
}

Configuration Commands

manx config --show                    # Show current settings
manx config --api-key YOUR_KEY       # Set Context7 API key
manx config --cache-dir /path/cache  # Set cache directory
manx config --auto-cache on          # Enable auto-caching
manx config --auto-cache off         # Disable auto-caching

# Note: Default result limit (10) is configurable in config.json

Environment Variables

export NO_COLOR=1              # Disable colored output
export MANX_CACHE_DIR=~/cache  # Custom cache directory  
export MANX_API_KEY=sk-xxx     # API key (overrides config)
export MANX_DEBUG=1            # Enable debug logging

Manx is designed for speed and efficiency:

Metric Value Notes
Binary Size 2.9MB Single static binary
Startup Time < 50ms Near-instantaneous
Search Speed < 1s Including network + parsing
Memory Usage < 10MB Minimal RAM footprint
Cache Size 100MB max Auto-managed, configurable
Offline Mode ✅ Full functionality with cache

Benchmarks

# Cold search (first time)
$ time manx fastapi
Real: 0.8s  User: 0.1s  Sys: 0.05s

# Warm search (cached)  
$ time manx --offline fastapi
Real: 0.1s  User: 0.08s  Sys: 0.02s

# Export benchmark
$ time manx fastapi -o docs.md
Real: 0.9s  User: 0.15s  Sys: 0.08s

Common Issues

"No results found"

# Check if library name is correct
manx config --show                    # Verify settings
manx fastapi                          # Try exact library name
manx python                           # Try broader search

# Clear cache and retry
manx cache clear
manx fastapi

Network/Connectivity Issues

# Test with debug mode
manx --debug fastapi

# Use offline mode if you have cache
manx --offline fastapi

# Check Context7 status
curl -I https://mcp.context7.com/mcp

Cache Issues

# Check cache stats
manx cache stats

# Clear and rebuild cache
manx cache clear
manx fastapi                          # Rebuild cache

# Use custom cache location
manx config --cache-dir ~/my-cache

Permission Issues

# Fix binary permissions
chmod +x /usr/local/bin/manx

# Alternative install location (no sudo)
mkdir -p ~/.local/bin
mv manx ~/.local/bin/
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Logs and Debug Info

# Enable debug mode
manx --debug fastapi 2>&1 | tee debug.log

# Check cache directory
ls -la ~/.cache/manx/

# View config file
cat ~/.config/manx/config.json

Remove Manx completely:

# Remove binary
sudo rm /usr/local/bin/manx

# Remove config and cache
rm -rf ~/.config/manx
rm -rf ~/.cache/manx

# Or use the installer  
curl -fsSL https://raw.githubusercontent.com/neur0map/manx/main/install.sh | bash -s -- --uninstall

Contributing

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

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature-name
  3. Make changes and add tests
  4. Run tests: cargo test
  5. Check formatting: cargo fmt --check
  6. Run linter: cargo clippy
  7. Submit a Pull Request

Development Setup

git clone https://github.com/neur0map/manx.git
cd manx
cargo build
cargo test
./target/debug/manx --help

License

MIT License - see LICENSE for details

Acknowledgments

  • Context7 for the excellent MCP documentation API
  • Rust community for amazing crates and tooling
  • Clap for beautiful CLI parsing
  • All contributors who make Manx better

Built with ❤️ for developers who live in the terminal.

⬆️ Back to Top