Usage Examples

Quick Start Example

The simplest way to get started:

# Run the interactive setup
npx megallm@latest

# Output:
#   __  __                _    _     __  __
#  |  \/  | ___  __ _  __ _| |   | |   |  \/  |
#  | |\/| |/ _ \/ _` |/ _` | |   | |   | |\/| |
#  | |  | |  __/ (_| | (_| | |___| |___| |  | |
#  |_|  |_|\___|\__, |\__,_|_____|_____|_|  |_|
#               |___/
#
# 🚀 MegaLLM CLI Setup Tool
# Supported: Claude Code, Codex/Windsurf, OpenCode
#
# ✓ System detected: Linux (bash)
# ✓ Tools detected: Claude Code ✓
#
# ? Which tool would you like to configure? Claude Code
# ? Setup level? System-level (global)
# ? Do you have a MegaLLM API key? Yes
# ? Enter your MegaLLM API key: sk-mega-***
#
# Configuration Summary:
# - Tool: Claude Code
# - Level: System-level
# - API Key: sk-mega-***86b9 (last 4 chars)
#
# ? Apply this configuration? Yes
#
# ✓ Configuration applied successfully!
# ✓ Shell reloaded
#
# 🎉 Setup complete! You can now use Claude Code with MegaLLM.

Scenario-Based Examples

Example 1: First-Time Setup for Claude Code

Setting up Claude Code for the first time on a new machine:

# Step 1: Run the CLI
npx megallm@latest

# Step 2: Follow the prompts
# System detected ✓
# Claude Code detected ✓
#
# ? Which tool would you like to configure?
#   › Claude Code
#     Codex/Windsurf
#     OpenCode
#     Configure All

# Step 3: Choose setup level
# ? Setup level?
#   › System-level (global) - Applies to all projects
#     Project-level (local) - Current directory only

# Step 4: API Key
# ? Do you have a MegaLLM API key?
#   › Yes
#     No - Show me how to get one

# ? Enter your MegaLLM API key:
# sk-mega-****************************************************************
  
# Step 5: Confirm and apply
# Configuration Summary:
# Tool: Claude Code
# Level: System-level
# Files: ~/.claude/settings.json, ~/.claude.json
# Env vars: ANTHROPIC_BASE_URL, ANTHROPIC_API_KEY
#
# ? Apply this configuration? Yes
#
# ✓ Created ~/.claude/settings.json
# ✓ Created ~/.claude.json
# ✓ Added environment variables to ~/.bashrc
# ✓ Configuration applied successfully!

Example 2: Project-Specific Setup

Setting up MegaLLM for a specific project:

# Navigate to your project
cd ~/projects/my-app

# Run the CLI
npx megallm@latest

# Choose project-level setup
# ? Setup level?
#   System-level (global)
#   › Project-level (local) - Current directory only

# After configuration:
ls -la .claude/
# .claude/
#   settings.json
#   settings.local.json

# Add to .gitignore
echo ".claude/settings.local.json" >> .gitignore

# Commit project settings (without API key)
cat .claude/settings.json
# {
#   "env": {
#     "ANTHROPIC_BASE_URL": "https://ai.megallm.io"
#   }
# }

git add .claude/settings.json .gitignore
git commit -m "Add MegaLLM configuration"

Example 3: Configuring Multiple Tools

Set up both Claude Code and Codex:

# Run the CLI
npx megallm@latest

# Select multiple tools
# ? Which tool would you like to configure?
#   Claude Code
#   Codex/Windsurf
#   OpenCode
#   › Configure All

# CLI will configure each tool in sequence
# 1. Configuring Claude Code...
#    ✓ Claude Code configured
#
# 2. Configuring Codex...
#    ✓ Codex configured
#
# 3. Configuring OpenCode...
#    ✓ OpenCode configured
#
# ✓ All tools configured successfully!

Example 4: Updating Existing Configuration

Update your configuration with a new API key:

# Run the CLI again
npx megallm@latest

# Existing configuration detected
# Found MegaLLM configuration:
# - ~/.claude/settings.json
# - ~/.codex/config.toml
#
# ? What would you like to do?
#   › Override (remove old, apply new)
#     Skip (keep existing)
#     Cancel

# Choose Override
# ? Which tool would you like to reconfigure?
#   › Claude Code
#     Codex/Windsurf
#     Both

# Enter new API key
# ? Enter your new MegaLLM API key: sk-mega-new-key-here

# ✓ Backed up old configuration
# ✓ Applied new configuration

Example 5: Team Setup with Shared Config

Set up MegaLLM for a team project with version-controlled configuration:

# Project maintainer: Create base configuration
cd ~/projects/team-project
npx megallm@latest

# Choose project-level
# Setup level: Project-level

# Create .claude/settings.json (without API key)
cat > .claude/settings.json << 'EOF'
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://ai.megallm.io"
  }
}
EOF

# Document API key requirement
cat > .claude/README.md << 'EOF'
# MegaLLM Setup

To use this project with MegaLLM:

1. Get your API key from https://megallm.io/dashboard
2. Create `.claude/settings.local.json`:
   {
     "env": {
       "ANTHROPIC_API_KEY": "your-api-key-here"
     }
   }
3. Or set environment variable:
   export ANTHROPIC_API_KEY="your-api-key-here"
EOF

# Commit shared configuration
git add .claude/settings.json .claude/README.md
git commit -m "Add MegaLLM team configuration"

# Team members: Clone and add their own API key
git clone repo
cd repo
echo '{ "env": { "ANTHROPIC_API_KEY": "my-key" } }' > .claude/settings.local.json

Example 6: Debug Mode for Troubleshooting

Use debug mode to diagnose issues:

# Run with debug output
DEBUG=* npx megallm@latest

# Detailed output shows:
# DEBUG: Detecting OS...
# DEBUG: OS: Linux
# DEBUG: Shell: bash
# DEBUG: Shell config: /home/user/.bashrc
# DEBUG: Checking for Claude Code...
# DEBUG: Claude Code found: /usr/local/bin/claude
# DEBUG: Checking for existing config...
# DEBUG: Found: /home/user/.claude/settings.json
# DEBUG: Parsing config file...
# DEBUG: Config valid: true
# ... more detailed logs ...

Example 7: Automated CI/CD Setup

Use the CLI in CI/CD pipelines:

name: Setup MegaLLM
on: [push]

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

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Configure MegaLLM
        env:
          ANTHROPIC_API_KEY: ${{ secrets.MEGALLM_API_KEY }}
          ANTHROPIC_BASE_URL: https://ai.megallm.io
        run: |
          mkdir -p .claude
          cat > .claude/settings.json << EOF
          {
            "env": {
              "ANTHROPIC_BASE_URL": "$ANTHROPIC_BASE_URL",
              "ANTHROPIC_API_KEY": "$ANTHROPIC_API_KEY"
            }
          }
          EOF

      - name: Run tests with Claude Code
        run: npm test

setup_megallm:
  stage: setup
  image: node:18
  script:
    - mkdir -p .claude
    - |
      cat > .claude/settings.json << EOF
      {
        "env": {
          "ANTHROPIC_BASE_URL": "https://ai.megallm.io",
          "ANTHROPIC_API_KEY": "${MEGALLM_API_KEY}"
        }
      }
      EOF
  variables:
    ANTHROPIC_BASE_URL: "https://ai.megallm.io"
  artifacts:
    paths:
      - .claude/

Example 8: Windsurf-Specific Setup

Configure Windsurf (Codex variant):

# Run the CLI
npx megallm@latest

# Select Codex
# ? Which tool would you like to configure?
#   Claude Code
#   › Codex/Windsurf
#     OpenCode

# Note: Windsurf is automatically detected
# ✓ Windsurf variant detected

# Configuration proceeds normally
# Creates ~/.codex/config.toml
# Sets MEGALLM_API_KEY environment variable

# Verify configuration
cat ~/.codex/config.toml
# model_provider = "megallm"
# model = "gpt-5"
#
# [model_providers.megallm]
# name = "OpenAI using Chat Completions"
# base_url = "https://ai.megallm.io/v1"
# env_key = "MEGALLM_API_KEY"

Advanced Scenarios

Switching Between Different APIs

Use different configurations for different projects:

# Project A: Use MegaLLM
cd ~/projects/project-a
npx megallm@latest
# Configure with MegaLLM API key

# Project B: Use different API
cd ~/projects/project-b
# Create custom configuration
cat > .claude/settings.json << 'EOF'
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://other-api.com",
    "ANTHROPIC_API_KEY": "other-key"
  }
}
EOF

Environment-Specific Configurations

Different configurations for development, staging, production:

# Development
export ANTHROPIC_API_KEY="sk-mega-dev-key"

# Staging
export ANTHROPIC_API_KEY="sk-mega-staging-key"

# Production
export ANTHROPIC_API_KEY="sk-mega-prod-key"

# Or use different config files
cp .claude/settings.dev.json .claude/settings.json  # for dev
cp .claude/settings.prod.json .claude/settings.json  # for prod

Docker Container Setup

Use MegaLLM in Docker containers:

FROM node:18

# Install MegaLLM CLI globally
RUN npm install -g megallm

# Set environment variables
ENV ANTHROPIC_BASE_URL=https://ai.megallm.io
ENV ANTHROPIC_API_KEY=your-key-here

# Create configuration directory
RUN mkdir -p /root/.claude

# Copy configuration file
COPY .claude/settings.json /root/.claude/settings.json

# Your app setup
WORKDIR /app
COPY . .
RUN npm install

CMD ["npm", "start"]

Common Workflows

Workflow 1: New Developer Onboarding

# 1. New developer clones the repository
git clone https://github.com/company/project.git
cd project

# 2. Sees MegaLLM setup instructions in README
cat README.md
# "Get your API key from https://megallm.io/dashboard"

# 3. Gets API key from dashboard
# Opens https://megallm.io/dashboard in browser

# 4. Runs setup (with NO_BANNER for cleaner output)
NO_BANNER=1 npx megallm@latest

# 5. Enters API key when prompted
# Configuration automatically merges with project settings

# 6. Starts developing
npm run dev

Workflow 2: Migration from OpenAI

# 1. Currently using OpenAI directly
# .env file has: MEGALLM_API_KEY=sk-mega-...

# 2. Switch to MegaLLM
npx megallm@latest

# 3. CLI detects Claude Code/Codex and configures
# Sets ANTHROPIC_BASE_URL=https://ai.megallm.io

# 4. Update application code (if needed)
# Change: base_url from api.openai.com to ai.megallm.io
# Or: Let environment variables handle it automatically

# 5. Test the migration
npm test

# 6. Deploy with new configuration

Workflow 3: Multi-Tool Development

# Developer using both Claude Code and Codex
npx megallm@latest

# Configure all tools at once
# ? Which tool? Configure All

# Result:
# - Claude Code uses ANTHROPIC_* env vars
# - Codex uses MEGALLM_API_KEY env var
# - Both point to ai.megallm.io

# Can switch between tools seamlessly
claude-code  # Uses ANTHROPIC_API_KEY
codex        # Uses MEGALLM_API_KEY

Troubleshooting Examples

Example: Permission Denied

# Error during setup
npx megallm@latest
# Error: EACCES: permission denied, mkdir '/home/user/.claude'

# Fix permissions
sudo chown -R $USER ~/.claude ~/.codex
chmod -R 755 ~/.claude ~/.codex

# Retry
npx megallm@latest

Example: Configuration Not Loading

# Check if environment variables are set
env | grep -E "ANTHROPIC|MEGALLM"
# (no output = not set)

# Reload shell configuration
source ~/.bashrc  # or ~/.zshrc

# Or restart terminal
exit
# Open new terminal and check again
env | grep -E "ANTHROPIC|MEGALLM"
# ANTHROPIC_BASE_URL=https://ai.megallm.io
# ANTHROPIC_API_KEY=sk-mega-...

Example: API Key Validation Failed

npx megallm@latest

# ? Enter your MegaLLM API key: sk-mega-abc
# ✗ API key must be at least 20 characters long

# Fix: Enter complete API key
# ? Enter your MegaLLM API key: sk-mega-****************************************************************
# ✓ API key validated

Next Steps

Review Configuration Details
Read the FAQ
Check Troubleshooting Guide for common issues

Getting Started

Configuration

Guides

Quick Start Example

Scenario-Based Examples

Example 1: First-Time Setup for Claude Code

Example 2: Project-Specific Setup

Example 3: Configuring Multiple Tools

Example 4: Updating Existing Configuration

Example 5: Team Setup with Shared Config

Example 6: Debug Mode for Troubleshooting

Example 7: Automated CI/CD Setup

Example 8: Windsurf-Specific Setup

Advanced Scenarios

Switching Between Different APIs

Environment-Specific Configurations

Docker Container Setup

Common Workflows

Workflow 1: New Developer Onboarding

Workflow 2: Migration from OpenAI

Workflow 3: Multi-Tool Development

Troubleshooting Examples

Example: Permission Denied

Example: Configuration Not Loading

Example: API Key Validation Failed

Next Steps

​Quick Start Example

​Scenario-Based Examples

​Example 1: First-Time Setup for Claude Code

​Example 2: Project-Specific Setup

​Example 3: Configuring Multiple Tools

​Example 4: Updating Existing Configuration

​Example 5: Team Setup with Shared Config

​Example 6: Debug Mode for Troubleshooting

​Example 7: Automated CI/CD Setup

​Example 8: Windsurf-Specific Setup

​Advanced Scenarios

​Switching Between Different APIs

​Environment-Specific Configurations

​Docker Container Setup

​Common Workflows

​Workflow 1: New Developer Onboarding

​Workflow 2: Migration from OpenAI

​Workflow 3: Multi-Tool Development

​Troubleshooting Examples

​Example: Permission Denied

​Example: Configuration Not Loading

​Example: API Key Validation Failed

​Next Steps

Quick Start Example

Scenario-Based Examples

Example 1: First-Time Setup for Claude Code

Example 2: Project-Specific Setup

Example 3: Configuring Multiple Tools

Example 4: Updating Existing Configuration

Example 5: Team Setup with Shared Config

Example 6: Debug Mode for Troubleshooting

Example 7: Automated CI/CD Setup

Example 8: Windsurf-Specific Setup

Advanced Scenarios

Switching Between Different APIs

Environment-Specific Configurations

Docker Container Setup

Common Workflows

Workflow 1: New Developer Onboarding

Workflow 2: Migration from OpenAI

Workflow 3: Multi-Tool Development

Troubleshooting Examples

Example: Permission Denied

Example: Configuration Not Loading

Example: API Key Validation Failed

Next Steps