FAQ

General Questions

What is the MegaLLM CLI?

The MegaLLM CLI is an interactive setup tool that configures AI coding assistants (Claude Code, Codex/Windsurf, and OpenCode) to use the MegaLLM AI service. It automates the configuration process, manages API keys securely, and provides a seamless setup experience across different platforms.

Which AI tools are supported?

The CLI currently supports:

Claude Code - System-level and project-level configuration
Codex/Windsurf - System-level configuration only
OpenCode - System-level and project-level configuration

More tools may be added in future releases.

Do I need to install the CLI?

No! You can run it directly using npx:

npx megallm@latest

However, you can also install it globally if you prefer:

npm install -g megallm

What are the system requirements?

Node.js: Version 18.0.0 or higher
Operating System: macOS, Linux, or Windows
Shell: bash, zsh, fish, or PowerShell

Check your Node.js version with: node --version

Installation & Setup

How do I get a MegaLLM API key?

Visit megallm.io/dashboard
Sign up or log in to your account
Navigate to the API Keys section
Click “Create New API Key”
Copy your API key (starts with sk-mega-)
Save it securely - you won’t be able to see it again

The CLI can open this page for you automatically during setup.

What's the difference between system-level and project-level configuration?

System-Level (Global):

Applies to all projects on your machine
Stored in your home directory (~/.claude/, ~/.codex/, etc.)
Best for personal development environments
Easier to manage for single developers

Project-Level (Local):

Applies only to the current project directory
Stored in the project folder (./.claude/, ./opencode.json, etc.)
Best for team projects with shared configurations
Allows different API keys per project
Can be version-controlled (without exposing API keys)

Important: Codex/Windsurf only supports system-level configuration.

How do I configure multiple tools?

When running the CLI, you’ll be asked which tool to configure:

? Which tool would you like to configure?
  Claude Code
  Codex/Windsurf
  OpenCode
  Configure All  ← Select this option

Selecting “Configure All” will set up all detected tools in sequence.Alternatively, run the CLI multiple times and select one tool each time.

Will the CLI install AI tools if they're missing?

Yes! If the CLI detects that a tool is not installed, it will offer to install it:

? Claude Code is not installed. Would you like to install it? (Y/n)

The CLI installs tools via NPM as global packages.

Configuration

Where are configuration files stored?

Claude Code:

System: ~/.claude/settings.json, ~/.claude.json
Project: ./.claude/settings.json or ./.claude/settings.local.json

Codex/Windsurf:

System: ~/.codex/config.toml

OpenCode:

System: ~/.config/opencode/opencode.json
Project: ./opencode.json

Environment Variables:

bash: ~/.bashrc
zsh: ~/.zshrc
fish: ~/.config/fish/config.fish
PowerShell: PowerShell profile

What if I already have MegaLLM configured?

The CLI will detect existing configurations and ask what you’d like to do:

Found existing MegaLLM configuration:
- ~/.claude/settings.json
- ~/.codex/config.toml

? What would you like to do?
  Override (remove old, apply new)
  Skip (keep existing)
  Cancel

Selecting “Override” will:

Create backup files (.backup suffix)
Remove old configuration
Apply new configuration

Selecting “Skip” will keep your existing setup and exit.

How do I update my API key?

Simply run the CLI again and choose “Override” when prompted about existing configuration:

npx megallm@latest

# Choose: Override (remove old, apply new)
# Enter your new API key

The CLI will backup your old configuration before applying the new one.

Can I use different API keys for different projects?

Yes! Use project-level configuration:

# Project A
cd ~/projects/project-a
npx megallm@latest
# Choose: Project-level
# Enter API key for Project A

# Project B
cd ~/projects/project-b
npx megallm@latest
# Choose: Project-level
# Enter API key for Project B

Each project will have its own .claude/settings.json with its own API key.

Troubleshooting

The CLI says a tool is installed but I can't find it

The CLI checks for tools using these methods:

NPM global package list
Command availability in PATH
Known installation directories

If detection fails:

Ensure the tool is installed globally: npm list -g --depth=0
Check if the command is available: which claude-code or which codex
Restart your terminal
Try installing manually: npm install -g @anthropic-ai/claude-code

I get 'permission denied' errors

This usually means you don’t have write access to the configuration directories.macOS/Linux Fix:

# Fix ownership of config directories
sudo chown -R $USER ~/.claude ~/.codex ~/.config/opencode

# Fix permissions
chmod -R 755 ~/.claude ~/.codex ~/.config/opencode

Windows Fix:

Run your terminal as Administrator
Or: Fix permissions in File Explorer → Properties → Security

My configuration isn't being used

Check 1: Environment Variables

# Claude Code
echo $ANTHROPIC_BASE_URL
echo $ANTHROPIC_API_KEY

# Codex
echo $MEGALLM_API_KEY

If empty, reload your shell:

source ~/.bashrc  # or ~/.zshrc
# Or restart your terminal

Check 2: Configuration Files

# Claude Code
cat ~/.claude/settings.json

# Codex
cat ~/.codex/config.toml

Verify the files exist and contain your API key.Check 3: File Permissions

ls -la ~/.claude/settings.json
ls -la ~/.codex/config.toml

Files should be readable by your user.

I get 'Invalid API key' errors

Verify key format: Should start with sk-mega-
Check for typos: Copy-paste the key directly from the dashboard
Trim whitespace: Remove any spaces before/after the key
Key length: Must be at least 20 characters
Regenerate: Create a new API key at megallm.io/dashboard

Test your API key:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://ai.megallm.io/v1/models

How do I completely remove MegaLLM configuration?

Remove Configuration Files:

# Claude Code
rm -rf ~/.claude/settings.json ~/.claude.json

# Codex
rm -rf ~/.codex/config.toml

# OpenCode
rm -rf ~/.config/opencode/opencode.json

# Project-level
rm -rf ./.claude ./opencode.json

Remove Environment Variables: Edit your shell config file (~/.bashrc, ~/.zshrc, etc.) and remove these lines:

export ANTHROPIC_BASE_URL="https://ai.megallm.io"
export ANTHROPIC_API_KEY="sk-mega-..."
export MEGALLM_API_KEY="sk-mega-..."

Then reload: source ~/.bashrc or restart terminal.

Can I see what the CLI is doing in detail?

Yes! Run in debug mode:

DEBUG=* npx megallm@latest

This will show detailed logs of:

System detection
Tool detection
File operations
Configuration changes
Error stack traces

Advanced Usage

Can I use the CLI in CI/CD pipelines?

Yes, but it’s better to configure manually in CI/CD environments:

# GitHub Actions example
- name: Configure MegaLLM
  env:
    ANTHROPIC_API_KEY: ${{ secrets.MEGALLM_API_KEY }}
  run: |
    mkdir -p .claude
    echo '{"env":{"ANTHROPIC_BASE_URL":"https://ai.megallm.io","ANTHROPIC_API_KEY":"'$ANTHROPIC_API_KEY'"}}' > .claude/settings.json

This avoids interactive prompts and is more reliable in automated environments.

How do I configure MegaLLM in a Docker container?

Add configuration during Docker build:

FROM node:18

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

# Or copy configuration files
COPY .claude/settings.json /root/.claude/settings.json

WORKDIR /app
COPY . .
RUN npm install
CMD ["npm", "start"]

Or pass API key at runtime:

docker run -e ANTHROPIC_API_KEY=sk-mega-... myimage

Can I version control my configuration?

Yes, but carefully:DO commit:

Project-level configuration WITHOUT API keys
.claude/settings.json with only ANTHROPIC_BASE_URL
Documentation for team members

DON’T commit:

API keys
.claude/settings.local.json
Personal environment variables

Example .claude/settings.json for version control:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://ai.megallm.io"
  }
}

Add to .gitignore:

.claude/settings.local.json
.claude.json

Team members add their own API key:

# .claude/settings.local.json (not committed)
{
  "env": {
    "ANTHROPIC_API_KEY": "sk-mega-personal-key"
  }
}

Can I use different models with each tool?

Yes! Each tool’s configuration file allows you to specify the model.Claude Code (~/.claude/settings.json):

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://ai.megallm.io",
    "ANTHROPIC_API_KEY": "sk-mega-...",
    "ANTHROPIC_MODEL": "claude-opus-4-1-20250805"
  }
}

Codex (~/.codex/config.toml):

model = "gpt-5"  # Change to any supported model

OpenCode (~/.config/opencode/opencode.json):

{
  "model": "gemini-2.5-pro"
}

See Models Catalog for available models.

What happens to my backups?

The CLI creates backup files before modifying configurations:

~/.claude/settings.json.backup
~/.codex/config.toml.backup
~/.config/opencode/opencode.json.backup

Backups are created with the .backup suffix and contain your previous configuration.To restore from backup:

mv ~/.claude/settings.json.backup ~/.claude/settings.json

You can delete backups manually if you don’t need them:

rm ~/.claude/*.backup ~/.codex/*.backup

Getting Help

Where can I get support?

Documentation:

Main Docs: docs.megallm.io
API Reference: docs.megallm.io/api

Support Channels:

Email: support@megallm.io
GitHub Issues: github.com/Megallm/megallm-npm/issues
Discord: discord.gg/Megallm

Community:

Twitter/X: @megallmio
YouTube: youtube.com/@Megallmio

How do I report a bug?

Check existing issues: github.com/Megallm/megallm-npm/issues
If not found, create a new issue with:
- CLI version: npx megallm@latest --version
- Node.js version: node --version
- Operating system
- Shell type
- Error message/logs (run with DEBUG=*)
- Steps to reproduce

How do I request a feature?

Open a feature request on GitHub: github.com/Megallm/megallm-npm/issues/newInclude:

Description of the feature
Use case / why it’s needed
Any relevant examples or mockups

Still Have Questions?

Can’t find your answer? We’re here to help!

Email Support

Get help from our support team

GitHub Issues

Report bugs or request features

Discord Community

Chat with the community

Documentation

Browse complete documentation

Getting Started

Configuration

Guides

General Questions

Installation & Setup

Configuration

Troubleshooting

Advanced Usage

Getting Help

Still Have Questions?

Email Support

GitHub Issues

Discord Community

Documentation

​General Questions

​Installation & Setup

​Configuration

​Troubleshooting

​Advanced Usage

​Getting Help

​Still Have Questions?

Email Support

GitHub Issues

Discord Community

Documentation

General Questions

Installation & Setup

Configuration

Troubleshooting

Advanced Usage

Getting Help

Still Have Questions?