apimgr

README

API Manager (apimgr)

中文版

A modern, feature-rich command-line tool for managing API configurations and testing connectivity. apimgr simplifies working with multiple API providers by centralizing configuration management with secure storage and seamless shell integration.(This project is only compatible with Claude Code for the time being, more tools like codex or gemini will be available in the future. )

!!!WARNING : this may override your ~/.cladue/setting.json file,please remember to BACKUP.

Features

Core Features

• Multi-Provider Support: Manage configurations for Anthropic, OpenAI, Doubao, and custom API providers
• Connectivity Testing: Validate API endpoints with customizable requests and detailed error diagnostics
• Easy Configuration Switching: Seamlessly switch between different API configurations globally or locally
• Shell Integration: Automatically export configurations to environment variables for tools like Claude Code
• JSON Output: Machine-readable results for scripting and automation workflows
• Secure Storage: Encrypted storage for API keys (optional) with configurable security settings
• Cross-Platform: Native support for macOS, Linux, and Windows

Advanced Features

• Interactive TUI: Full-featured terminal user interface with keyboard navigation (just run apimgr without arguments)
• Interactive Editing: Intuitive interactive commands for adding and modifying configurations
• Dual Configuration Modes:
  • Global: Persistent configuration across all shells
  • Local: Temporary configuration for current shell session only (-l/--local flag)
• Comprehensive Status Checking: View both global and shell environment configurations in one command
• XDG Compliance: Follows XDG Base Directory Specification on Linux systems
• Auto-Synchronization: Sync configurations with supported tools (Claude Code, etc.)
• Rich Diagnostics: Detailed error messages for timeout, connection refused, DNS failures, and more

Installation

Prerequisites

• Go 1.24 or higher (for source compilation)

Recommended Installation

Go Install

go install github.com/ccasJay/apimgr@latest

From Source

git clone https://github.com/ccasJay/apimgr.git
cd apimgr
go build
sudo mv apimgr /usr/local/bin/  # Optional: install system-wide

Using Makefile

git clone https://github.com/ccasJay/apimgr.git

cd apimgr
make build          # Build ./apimgr
sudo make install   # Install to /usr/local/bin
make install-local  # Install to ~/.local/bin

Quick Start

TUI Mode (Recommended)

Simply run apimgr without arguments to launch the interactive TUI:

apimgr

TUI Keyboard Shortcuts:

Key	Action
j/k or ↑/↓	Move up/down
g/G	Jump to top/bottom
Enter	View details
s	Switch config locally (Claude Code)
S	Switch config globally
a	Add config
e	Edit config
d	Delete config
p	Ping test
t	Compatibility test
m	Switch model
?	Help
q	Quit

CLI Mode

1. Add a new configuration

   apimgr add my-config --sk sk-ant-api03-... --url https://api.anthropic.com
   

   or just use

   apimgr add
   

2. List all configurations

   apimgr list
   

3. Switch to a configuration

   apimgr switch my-config  # Global switch
   apimgr switch -l my-config  # Local (current shell only)
   

4. Test connectivity

   apimgr ping  # Test active configuration
   apimgr ping -u https://api.example.com  # Test custom URL
   apimgr ping -T -p /chat/completions  # Test real API endpoint with POST request
   

5. Check current status

   apimgr status
   

For detailed usage, see the Quick Start Guide.

Configuration

Configuration Paths

• Default: ~/.config/apimgr/config.json (XDG compliant on Linux)
• Legacy: ~/.apimgr.json (automatically migrated to new path)
• Custom: Use XDG_CONFIG_HOME to specify a custom directory:

  XDG_CONFIG_HOME=~/.myconfig apimgr add my-config --sk sk-xxx...
  

Configuration Format

{
  "configs": [
    {
      "alias": "my-config",
      "api_key": "sk-ant-api03-...",
      "auth_token": "",
      "base_url": "https://api.anthropic.com",
      "model": "claude-3-opus-20240229",
      "provider": "anthropic"
    }
  ],
  "active": "my-config"
}

Provider Auto-Detection

When the provider field is not explicitly set, apimgr will automatically detect the provider based on the base URL:

URL Pattern	Detected Provider
*api.anthropic.com*	anthropic
*api.openai.com*	openai
Other URLs	anthropic (default)

This means you can omit the provider field when adding configurations with standard API URLs:

# Provider will be auto-detected as "anthropic"
apimgr add my-anthropic --sk sk-ant-... --url https://api.anthropic.com

# Provider will be auto-detected as "openai"
apimgr add my-openai --sk sk-... --url https://api.openai.com

## Commands

### TUI Mode
```bash
apimgr            # Launch interactive TUI interface

Basic Commands

apimgr add        # Add a new API configuration (interactive or non-interactive)
apimgr list       # List all saved configurations with active indicator
apimgr switch     # Switch to a configuration (global or local)
apimgr ping       # Test API connectivity with detailed diagnostics
apimgr status     # Show combined global and shell configuration status
apimgr edit       # Edit an existing configuration (interactive or non-interactive)
apimgr remove     # Remove a configuration

Command Details

apimgr ping

Test API connectivity with customizable options:

apimgr ping [alias]          # Test specific or active configuration
apimgr ping -u URL           # Test custom URL
apimgr ping -X GET           # Use specific HTTP method
apimgr ping -t 30s           # Custom timeout
apimgr ping -j               # JSON output
apimgr ping -T               # Test real API compatibility (auto-detects provider from URL)
apimgr ping -T -p /chat/completions  # Test real API with custom endpoint path
apimgr ping -T --stream      # Test streaming API compatibility
apimgr ping -T -v            # Verbose output with request/response details

The -T flag enables compatibility testing mode, which:

• Sends a real chat completion request to validate API format
• Auto-detects the provider (Anthropic/OpenAI) from the base URL
• Validates response structure matches Claude Code expectations
• Supports streaming mode testing with --stream flag

apimgr status

Shows configuration source priority (shell environment overrides global):

Current configuration status:
=========================================
1. Global active configuration (config file):
   Alias: my-config
   API Key: sk-ant-api03-**************
   Base URL: https://api.anthropic.com
   Model: claude-3-opus-20240229

2. Current Shell environment:
   No environment variables set

=========================================
💡 Currently using global configuration (Shell has no environment variables set)

apimgr list

Lists configurations with active marker:

Available configurations:
* my-config: API Key: sk-ant-api03-************** (URL: https://api.anthropic.com, Model: claude-3-opus-20240229)
  openai-dev: API Key: sk-************** (URL: https://api.openai.com, Model: gpt-4o)

Environment Variables

apimgr automatically respects and displays these environment variables:

• ANTHROPIC_API_KEY
• ANTHROPIC_AUTH_TOKEN
• ANTHROPIC_BASE_URL
• ANTHROPIC_MODEL
• OPENAI_API_KEY
• OPENAI_BASE_URL
• OPENAI_MODEL
• APIMGR_ACTIVE

Usage Examples

Interactive Configuration

$ apimgr add
Enter config alias: my-anthropic
Enter API key: sk-ant-api03-...
Enter Authentication Token (press Enter to skip):
Enter Base URL (default: https://api.anthropic.com):
Enter Model name (press Enter to skip): claude-3-opus-20240229
✅ Configuration 'my-anthropic' added successfully

Non-Interactive Configuration

apimgr add openai-prod \
  --sk sk-... \
  --url https://api.openai.com \
  --model gpt-4o

Edit Configuration

# Interactive edit
apimgr edit my-config

# Non-interactive edit
apimgr edit my-config --url https://api.new-domain.com --model claude-3-sonnet-20240229

Local Configuration

apimgr switch -l temporary-config  # Use configuration only for current shell
apimgr status  # Shows both global and local configuration

Shell Integration

After installing the binary, run apimgr shell-install to enable shell integration for automatic configuration loading. The legacy apimgr install alias is still supported. Supported shells:

• Bash
• Zsh
• Fish

Troubleshooting

Common Errors

• Timeout Error: Increase timeout with -t flag (e.g., apimgr ping -t 30s)
• Connection Refused: Check if API server is running and accessible
• DNS Resolution Failed: Verify domain name and network connectivity
• Invalid URL: Ensure URL includes protocol (http:// or https://)

Detailed Diagnostics

Use apimgr ping -j for JSON output with full error details:

{
  "url": "https://api.example.com",
  "statusCode": 0,
  "statusText": "",
  "requestMethod": "HEAD",
  "durationMs": 10001,
  "timeoutMs": 10000,
  "success": false
}

Documentation

• Quick Start Guide
• Command Reference (TODO)
• Contribution Guide
• Code of Conduct
• Security Policy (TODO)

Contributing

We welcome contributions! Please read CONTRIBUTING.md for details on our code of conduct and development process.

License

MIT License - see LICENSE for details

Support

For issues, feature requests, or questions, please open an issue on GitHub.