clauver

  ██████╗██╗      █████╗ ██╗   ██╗██╗   ██╗███████╗██████╗
 ██╔════╝██║     ██╔══██╗██║   ██║██║   ██║██╔════╝██╔══██╗
 ██║     ██║     ███████║██║   ██║██║   ██║█████╗  ██████╔╝
 ██║     ██║     ██╔══██║██║   ██║╚██╗ ██╔╝██╔══╝  ██╔══██╗
 ╚██████╗███████╗██║  ██║╚██████╔╝ ╚████╔╝ ███████╗██║  ██║
  ╚═════╝╚══════╝╚═╝  ╚═╝ ╚═════╝   ╚═══╝  ╚══════╝╚═╝  ╚═╝

Claude Code Provider Manager - Switch between multiple Claude Code API providers seamlessly.

Overview

Clauver is a powerful CLI tool that allows you to easily manage and switch between different Claude Code API providers, including:

• Native Anthropic - Use your existing Claude Pro/Team subscription
• Z.AI - Zhipu AI's GLM models
• MiniMax - MiniMax AI's MiniMax-M2 model
• Kimi - Moonshot AI's Kimi K2 model
• KAT-Coder - Kwaipilot's KAT-Coder
• Custom Providers - Add your own provider

⚠️ Platform Compatibility: This script has been tested and confirmed to work on Linux only. While it may work on other Unix-like systems (macOS, WSL), compatibility is not guaranteed.

Features

• Easy Provider Switching - Switch providers with a single command
• Secure API Key Management - API keys encrypted with age (X25519)
• Configuration Testing - Test provider configurations before use
• Default Provider - Set a default provider for quick access
• Auto-completion - Tab completion for bash, zsh, and fish
• Quick Setup Wizard - Interactive setup for beginners
• Status Monitoring - Check all configured providers at once
• Self-Update - Update to the latest version with a single command
• Encrypted Storage - Secrets encrypted at rest, decrypted in memory only

Credits

Clauver is heavily inspired by clother by jolehuit. Special thanks to the original project for the inspiration and architectural concepts.

Installation

Quick Install

curl -fsSL https://raw.githubusercontent.com/dkmnx/clauver/main/install.sh | bash

The installer will:

• ✅ Check for the claude command
• ✅ Install clauver to ~/.clauver/bin/
• ✅ Set up auto-completion
• ✅ Add to PATH (if needed)

Manual Installation

# Clone the repository
git clone https://github.com/dkmnx/clauver clauver
cd clauver

# Install
mkdir -p ~/.clauver/bin
cp clauver.sh ~/.clauver/bin/clauver
chmod +x ~/.clauver/bin/clauver

# Add to PATH
echo 'export PATH="$HOME/.clauver/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Usage

Setup Wizard

clauver setup        # Interactive setup wizard

Configure Providers

clauver config zai           # Configure Z.AI
clauver config minimax       # Configure MiniMax
clauver config kimi          # Configure Kimi
clauver config katcoder      # Configure KAT-Coder
clauver config anthropic     # Configure Native Anthropic
clauver config custom        # Add custom provider

Use Providers

clauver anthropic    # Use Native Anthropic
clauver zai          # Use Z.AI
clauver minimax      # Use MiniMax
clauver kimi         # Use Kimi
clauver katcoder     # Use KAT-Coder
clauver <custom>     # Use custom provider

Default Provider

Set a default provider for quick access:

# Set default provider
clauver default zai

# Show current default
clauver default

# Use default provider (no arguments needed)
clauver "What can you help me with?"

Manage Providers

clauver list         # List all providers
clauver status       # Check provider status
clauver test <name>  # Test a provider
clauver migrate      # Migrate plaintext secrets to encrypted storage
clauver default      # Show or set default provider
clauver version      # Show current version and check for updates
clauver update       # Update to the latest version
clauver help         # Show help

Examples

Basic Usage

# First time setup
clauver setup

# Configure a provider
clauver config minimax
# Enter your MiniMax API key when prompted

# Use the provider
clauver minimax "Write a Python function to calculate fibonacci numbers"

# Check status
clauver status

Testing Configuration

# Test a specific provider
clauver test zai

# Test all providers
clauver status

Setting a Default Provider

# Set your preferred default provider
clauver default minimax

# Verify the default is set
clauver default

# Use the default provider
clauver "Help me write a bash script"

# Change your default anytime
clauver default anthropic

Version Management

# Check current version and available updates
clauver version

# Update to the latest version
clauver update

# Both commands work without confirmation prompts
# Update will show "already up to date" if on latest version

Encryption & Key Management

Encryption Overview

Clauver automatically encrypts all API keys using age, a modern and secure file encryption tool. Your secrets are:

• Encrypted at rest on disk
• Only decrypted into memory when needed
• Never written to disk as plaintext

Key Backup

CRITICAL: Back up your encryption key immediately after installation!

# Your encryption key location
~/.clauver/age.key

# Back up your key (choose one method):
cp ~/.clauver/age.key ~/backup/clauver-age.key.backup
cp ~/.clauver/age.key /path/to/external/drive/

Without your age key, you cannot decrypt your secrets!

Key Recovery

If you lose your encryption key:

# 1. If you have a backup, restore it:
cp ~/backup/clauver-age.key.backup ~/.clauver/age.key
chmod 600 ~/.clauver/age.key

# 2. If you don't have a backup, you'll need to reconfigure:
rm ~/.clauver/secrets.env.age  # Remove encrypted file
clauver config <provider>       # Reconfigure your providers

Migrating from Plaintext

If you're upgrading from an older version with plaintext secrets:

# Check your current storage type
clauver status

# Migrate to encrypted storage
clauver migrate

# Verify encryption is active
clauver status  # Should show "🔒 Secrets Storage: Encrypted"

Using Configs on Multiple Machines

Your encryption key is portable! To use your configs on another machine:

# On original machine - backup both files:
cp ~/.clauver/age.key ~/backup/
cp ~/.clauver/secrets.env.age ~/backup/

# On new machine - restore both files:
mkdir -p ~/.clauver
cp ~/backup/age.key ~/.clauver/
cp ~/backup/secrets.env.age ~/.clauver/
chmod 600 ~/.clauver/age.key
chmod 600 ~/.clauver/secrets.env.age

# Verify it works:
clauver list

Custom Provider

# Add a custom provider
clauver config custom
# Provider name: my-provider
# Base URL: https://api.example.com/anthropic
# API Key: your-api-key
# Model: your-model

# Use it
clauver my-provider "Hello"

Auto-completion

Clauver includes auto-completion for bash, zsh, and fish.

After installation, try:

clauver <TAB><TAB>        # Show available commands
clauver z<TAB>            # Complete to 'clauver zai'

Requirements

• claude CLI - Install with: npm install -g @anthropic-ai/claude-code
• age - For encryption: sudo apt install age (or brew install age on macOS)
• Bash/Zsh/Fish - For auto-completion
• API Keys - For third-party providers

Architecture

clauver/
├── clauver.sh              # Main CLI script
├── install.sh    # Installation script
├── completion/             # Auto-completion files
│   ├── clauver.bash
│   ├── clauver.zsh
│   └── clauver.fish
├── README.md               # This file
└── LICENSE                 # MIT license

Configuration Storage

Clauver uses an encrypted configuration system:

~/.clauver/
├── secrets.env.age        # Encrypted API keys (age encrypted)
├── age.key                # Encryption key (chmod 600) - BACK THIS UP!
├── config                 # Provider configurations (chmod 600)
├── bin/
│   └── clauver           # Installed binary
└── completions/          # Auto-completion files

Configuration Files

• secrets.env.age: Encrypted API keys using age (X25519) encryption

  • ZAI_API_KEY
  • MINIMAX_API_KEY
  • KIMI_API_KEY
  • KATCODER_API_KEY
  • Secrets are only decrypted into memory, never written to disk as plaintext

• age.key: Your encryption key (automatically generated)

  • CRITICAL: Back up this file! Without it, you cannot decrypt your secrets
  • Portable across machines - copy this file to use your configs elsewhere
  • Located at: ~/.clauver/age.key

• config: Stores provider configurations:

  • Base URLs, models, and endpoint IDs
  • Custom provider definitions
  • default_provider - Your preferred default provider

Security Features

• Encrypted at Rest: API keys are encrypted using age (modern, secure encryption)
• Memory-Only Decryption: Secrets decrypted directly into memory via process substitution
• No Plaintext on Disk: Encrypted file is never written as plaintext
• Session Caching: Secrets decrypted once per session for performance
• Automatic Key Generation: Encryption key auto-generated on first use
• Migration Support: Seamlessly migrate from plaintext to encrypted storage

Troubleshooting

PATH Issues

If clauver is not found after installation, export the path for the current session.

export PATH="$HOME/.clauver/bin:$PATH"

Make it permanent by adding the path to your shell config file.

# Bash
echo 'export PATH="$HOME/.clauver/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Zsh
echo 'export PATH="$HOME/.clauver/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Fish
echo 'set -gx PATH $HOME/.clauver/bin $PATH' >> ~/.config/fish/config.fish
source ~/.config/fish/config.fish

Provider Test Fails

1. Make sure you have a valid API key and valid subscription or enough credits for the provider.
2. Check your API key is correctly configured: clauver list
3. Ensure you have internet connectivity
4. Test the provider directly: clauver test <provider>

Claude Command Not Found

Install Claude Code CLI:

npm install -g @anthropic-ai/claude-code

API Key Won't Update

If updating an API key doesn't take effect:

# 1. Verify the new key was saved
clauver list

# 2. If it shows the old key, try reconfiguring
clauver config <provider>

# 3. Check your age key exists
ls -la ~/.clauver/age.key

# 4. If age key is missing, restore from backup or reconfigure

Encryption/Decryption Errors

If you see "Failed to decrypt secrets file" or similar errors:

# 1. Verify age is installed
age --version

# 2. Check if your age key exists and has correct permissions
ls -la ~/.clauver/age.key
chmod 600 ~/.clauver/age.key  # Fix permissions if needed

# 3. If age key is corrupted or lost, restore from backup:
cp ~/backup/clauver-age.key.backup ~/.clauver/age.key
chmod 600 ~/.clauver/age.key

# 4. If no backup exists, start fresh:
rm ~/.clauver/secrets.env.age
clauver config <provider>  # Reconfigure all providers

Missing age Command

If you see "age command not found":

# Debian/Ubuntu
sudo apt install age

# Fedora/RHEL
sudo dnf install age

# Arch Linux
sudo pacman -S age

# macOS
brew install age

# Verify installation
age --version

Corrupted Configuration

If clauver behaves unexpectedly:

# 1. Check current configuration
clauver list
clauver status

# 2. Backup your age key first (IMPORTANT!)
cp ~/.clauver/age.key ~/age.key.backup

# 3. Test decryption manually
age -d -i ~/.clauver/age.key ~/.clauver/secrets.env.age

# 4. If decryption fails, secrets file may be corrupted
# Remove and reconfigure (your age key is still safe):
rm ~/.clauver/secrets.env.age
clauver config <provider>

License

MIT (c) 2025 dkmnx