1 line
18 KiB
JSON
1 line
18 KiB
JSON
{"repo": "cexll/claude-code-env", "files": {"README.md": {"3dbea307f737b10e2def9e2d55725ed34a38551f": {"t": 1785674405.4432497, "n": 17338, "h": "9d268dc87bf9cc08", "c": "# Claude Code Environment Switcher (CCE)\n\n[](https://github.com/cexll/claude-code-env/releases)\n[](https://github.com/cexll/claude-code-env/blob/master/go.mod)\n[](https://github.com/cexll/claude-code-env/blob/master/LICENSE)\n[](https://github.com/cexll/claude-code-env/actions)\n\n[中文](./README_zh.md) [English](./README.md)\n\nA production-ready Go CLI tool that manages multiple Claude Code API endpoint configurations, enabling seamless switching between environments (production, staging, custom API providers, etc.). CCE acts as an intelligent wrapper around Claude Code with **flag passthrough**, **ANSI-free display management**, and **universal terminal compatibility**.\n\n## 🆕 What's New\n- **Automated Releases**: GitHub Actions workflow for multi-platform binary releases\n- **One-line Installation**: curl-based installer with SHA256 verification (Linux/macOS)\n- **--yolo flag**: Quick shortcut for Claude's `--dangerously-skip-permissions` flag\n- Per-environment API key env var selection: choose between `ANTHROPIC_API_KEY` (default) and `ANTHROPIC_AUTH_TOKEN`.\n- `cce add` includes a prompt to select the key variable name.\n- `cce list` now shows `Key Var: ...` for each environment.\n- API key validation is provider-agnostic (length and safety only) for better compatibility.\n\n## ✨ Key Features\n\n### 🎯 **Core Functionality**\n- **Environment Management**: Add, list, remove Claude Code configurations with interactive selection\n- **Additional Environment Variables**: Configure custom environment variables per environment (e.g., `ANTHROPIC_SMALL_FAST_MODEL`)\n- **Flag Passthrough**: Transparently forward arguments to Claude Code (`cce -r`, `cce --help`, etc.)\n- **Secure API Key Storage**: Hidden terminal input with masked display and proper file permissions\n- **Universal Terminal Support**: ANSI-free display system working across SSH, CI/CD, and all terminal types\n\n### 🖥️ **Advanced UI Features**\n- **Responsive Design**: Adapts to any terminal width (20-300+ columns tested)\n- **4-Tier Progressive Fallback**: Full interactive → Basic interactive → Numbered selection → Headless mode\n- **Smart Content Truncation**: Preserves essential information while preventing overflow\n- **Clean Navigation**: Stateful rendering prevents display stacking during arrow key navigation\n\n### 🔒 **Enterprise-Grade Security**\n- **Command Injection Prevention**: Comprehensive argument validation with shell metacharacter detection\n- **Secure File Operations**: Configuration stored with 600/700 permissions and atomic writes\n- **API Key Protection**: Terminal raw mode input with masked display (first 6 + last 4 chars)\n- **Input Sanitization**: URL validation, name sanitization, and format checking\n\n## 📦 Installation\n\n### Quick Install (Recommended)\n\n**For Linux and macOS:**\n\n```bash\n# Install latest version\ncurl -fsSL https://raw.githubusercontent.com/cexll/claude-code-env/master/install.sh | bash\n\n# Or install specific version\nVERSION=v2.4.0 bash -c \"$(curl -fsSL https://raw.githubusercontent.com/cexll/claude-code-env/master/install.sh)\"\n\n# Using wget\nwget -qO- https://raw.githubusercontent.com/cexll/claude-code-env/master/install.sh | bash\n```\n\nThe install script will:\n- ✅ Auto-detect your OS and architecture\n- ✅ Download the latest release from GitHub\n- ✅ Verify SHA256 checksum\n- ✅ Install to `/usr/local/bin/cce`\n- ✅ Set proper permissions\n\n**For Windows:**\nDownload the `.zip` file from [Releases](https://github.com/cexll/claude-code-env/releases/latest), extract it, and add to your PATH.\n\n### Alternative: Go Install\n\n```bash\n# Install latest version\ngo install github.com/cexll/claude-code-env@latest\n\n# Or install specific version\ngo install github.com/cexll/claude-code-env@v2.4.0\n```\n\n### Build from Source\n\n```bash\ngit clone https://github.com/cexll/claude-code-env.git\ncd claude-code-env\nmake build\nsudo make install # Installs to /usr/local/bin/\n```\n\n### Verify Installation\n\n```bash\ncce --version\n# Output: CCE version v2.4.0\n```\n\n## 🚀 Usage\n\n### Basic Commands\n\n#### Interactive Launch\n```bash\ncce # Shows responsive environment selection menu with arrow navigation\n```\n\n#### Launch with Specific Environment\n```bash\ncce --env production # or -e production\ncce -e staging # Launch with staging environment\n```\n\n#### Flag Passthrough Examples\n```bash\ncce -r # Pass -r flag directly to claude\ncce --env prod --verbose # Use prod environment, pass --verbose to claude\ncce -- --help # Show claude's help (-- explicitly separates flags)\ncce -e staging -- chat --interactive # Use staging, pass chat flags to claude\ncce --yolo # Quick shortcut for --dangerously-skip-permissions\ncce --env prod --yolo # Use prod env and skip permissions\n```\n\n### Environment Management\n\n#### Add a new environment:\n```bash\ncce add\n# Interactive prompts for:\n# - Environment name (validated)\n# - API URL (with format validation)\n# - API Key (secure hidden input)\n# - API Key Env Var Name (1=ANTHROPIC_API_KEY default, 2=ANTHROPIC_AUTH_TOKEN)\n# - Model (optional, e.g., claude-3-5-sonnet-20241022)\n# - Additional environment variables (optional, e.g., ANTHROPIC_SMALL_FAST_MODEL)\n```\n\n#### List all environments:\n```bash\ncce list\n# Output with responsive formatting:\n# Configured environments (3):\n#\n# Name: production\n# URL: https://api.anthropic.com\n# Model: claude-3-5-sonnet-20241022\n# Key: sk-ant-************************************************************\n# Key Var: ANTHROPIC_API_KEY\n# Env: ANTHROPIC_SMALL_FAST_MODEL=claude-3-haiku-20240307\n# CUSTOM_TIMEOUT=60s\n#\n# Name: staging\n# URL: https://staging.anthropic.com\n# Model: default\n# Key: sk-stg-************************************************************\n# Key Var: ANTHROPIC_API_KEY\n```\n\n#### Remove an environment:\n```bash\ncce remove staging\n# Confirmation and secure removal with backup\n```\n\n#### Using Additional Environment Variables:\nWhen adding a new environment, you can configure additional environment variables:\n\n```bash\ncce add\n# Example interactive session:\n# Environment name: kimi-k2\n# Base URL: https://api.moonshot.cn\n# API Key: [secure input]\n# Model: moonshot-v1-32k\n# Additional environment variables (optional):\n# Variable name: ANTHROPIC_SMALL_FAST_MODEL\n# Value for ANTHROPIC_SMALL_FAST_MODEL: claude-3-haiku-20240307\n# Variable name: ANTHROPIC_TIMEOUT\n# Value for ANTHROPIC_TIMEOUT: 30s\n# Variable name: [press Enter to finish]\n```\n\nThese environment variables will be automatically set when launching Claude Code with this environment.\n\n### Command Line Interface\n\n```bash\ncce [options] [-- claude-args...]\n\nOptions:\n -e, --env <name> Use specific environment\n -k, --key-var <name> Override API key env var for this run (ANTHROPIC_API_KEY|ANTHROPIC_AUTH_TOKEN)\n -h, --help Show comprehensive help with examples\n --yolo Quick shortcut for --dangerously-skip-permissions\n\nCommands:\n list List all environments with responsive formatting\n add Add new environment (supports model specification)\n remove <name> Remove environment with confirmation\n\nFlag Passthrough:\n Any arguments after CCE options are passed directly to claude.\n Use '--' to explicitly separate CCE options from claude arguments.\n\nExamples:\n cce Interactive selection and launch\n cce --env prod Launch with 'prod' environment\n cce -r Pass -r flag to claude with default environment\n cce --env staging --verbose Use staging, pass --verbose to claude\n cce --env dev -k ANTHROPIC_AUTH_TOKEN -- chat Override key var for this run\n cce -- --help Show claude's help\n cce --yolo Quick bypass of permissions check\n cce --env prod --yolo Use prod environment and skip permissions\n```\n\n## 📥 Releases\n\nCCE uses automated GitHub Actions workflows to build and release binaries for multiple platforms:\n\n- **Linux**: amd64, arm64\n- **macOS**: amd64 (Intel), arm64 (Apple Silicon)\n- **Windows**: amd64\n\nEach release includes:\n- Pre-built binaries for all platforms\n- SHA256 checksums for verification\n- Automated testing and quality checks\n\nDownload the latest release: [Releases Page](https://github.com/cexll/claude-code-env/releases/latest)\n\n## 📁 Configuration\n\n### Configuration File Structure\n\nEnvironments stored in `~/.claude-code-env/config.json`:\n\n```json\n{\n \"environments\": [\n {\n \"name\": \"production\",\n \"url\": \"https://api.anthropic.com\",\n \"api_key\": \"sk-ant-api03-xxxxx\",\n \"api_key_env\": \"ANTHROPIC_API_KEY\",\n \"model\": \"claude-3-5-sonnet-20241022\",\n \"env_vars\": {\n \"ANTHROPIC_SMALL_FAST_MODEL\": \"claude-3-haiku-20240307\"\n }\n },\n {\n \"name\": \"staging\",\n \"url\": \"https://staging.anthropic.com\",\n \"api_key\": \"sk-ant-staging-xxxxx\",\n \"api_key_env\": \"ANTHROPIC_AUTH_TOKEN\",\n \"model\": \"claude-3-haiku-20240307\",\n \"env_vars\": {\n \"ANTHROPIC_TIMEOUT\": \"30s\",\n \"ANTHROPIC_RETRY_COUNT\": \"3\"\n }\n }\n ],\n \"settings\": {\n \"validation\": {\n \"strict_validation\": true,\n \"model_patterns\": [\"^claude-.*$\"]\n }\n }\n}\n```\n\n### Environment Variables\n\n**Additional Environment Variables Support:**\nCCE supports configuring additional environment variables for each environment. These variables are automatically set when launching Claude Code with the selected environment.\n\n**API Key Env Var Name:**\n- Per environment, choose which variable name to export for the API key.\n- Supported values: `ANTHROPIC_API_KEY` (default) or `ANTHROPIC_AUTH_TOKEN`.\n- CCE sets only the selected one during launch, along with `ANTHROPIC_BASE_URL` and optional `ANTHROPIC_MODEL`.\n\n**Common Use Cases:**\n- `ANTHROPIC_SMALL_FAST_MODEL`: Specify a faster model for quick operations like code completion (e.g., `claude-3-haiku-20240307`)\n- `ANTHROPIC_TIMEOUT`: Set custom timeout values for API requests (e.g., `30s`)\n- `ANTHROPIC_RETRY_COUNT`: Configure retry behavior for failed requests (e.g., `3`)\n- Any custom environment variables required by your Claude Code setup\n\n**Model Validation Configuration:**\n- `CCE_MODEL_PATTERNS`: Comma-separated custom regex patterns for model validation\n- `CCE_MODEL_STRICT`: Set to \"false\" for permissive mode with warnings\n\n## 🏗️ Architecture\n\n### Core Components (4 Files)\n\n- **`main.go`** (580+ lines): CLI interface, **flag passthrough system**, model validation\n- **`config.go`** (367 lines): Atomic file operations, backup/recovery, validation\n- **`ui.go`** (1000+ lines): **ANSI-free display management**, responsive UI, 4-tier fallback\n- **`launcher.go`** (174 lines): Process execution with argument forwarding\n\n### Key Design Patterns\n\n**Flag Passthrough System**: Two-phase argument parsing separates CCE flags from Claude arguments, enabling transparent command forwarding with security validation.\n\n**ANSI-Free Display Management**: Universal terminal compatibility using:\n- **DisplayState**: Tracks screen content and manages stateful updates\n- **TextPositioner**: Cursor control using carriage return and padding (no ANSI)\n- **LineRenderer**: Stateful menu rendering with differential updates\n\n**4-Tier Progressive Fallback**:\n1. **Full Interactive**: Stateful rendering with arrow navigation and ANSI enhancements\n2. **Basic Interactive**: ANSI-free display with arrow key support\n3. **Numbered Selection**: Fallback for limited terminals\n4. **Headless Mode**: Automated mode for CI/CD environments\n\n## 🔒 Security Implementation\n\n### Multi-Layer Security\n- **Command Injection Prevention**: Comprehensive argument validation with shell metacharacter detection\n- **Secure File Operations**: Atomic writes with proper permissions (600 for files, 700 for directories)\n- **API Key Protection**: Terminal raw mode input, masked display, never logged\n- **Input Validation**: URL validation, name sanitization, API key format checking\n- **Process Isolation**: Clean environment variable handling with secure argument forwarding\n\n### Security Validation\n- **Timing Attack Resistance**: Secure comparison operations\n- **Memory Safety**: Proper cleanup and bounded operations\n- **Environment Sanitization**: Clean variable injection without exposure\n\n## 🧪 Testing & Quality\n\n### Comprehensive Test Coverage (95%+)\n\n```bash\n# Run full test suite\ngo test -v ./...\n\n# Security-specific tests\ngo test -v -run TestSecurity\n\n# Performance benchmarks\ngo test -bench=. -benchmem\n\n# Coverage analysis\ngo test -coverprofile=coverage.out\ngo tool cover -html=coverage.out\n```\n\n### Test Categories\n- **Unit Tests**: Core functionality (parseArguments, formatSingleLine, etc.)\n- **Integration Tests**: End-to-end workflows and cross-platform compatibility\n- **Security Tests**: Command injection prevention, file permissions, input validation\n- **Terminal Compatibility**: SSH, CI/CD, terminal emulators (iTerm, VS Code, etc.)\n- **Performance Tests**: Sub-microsecond operations, memory efficiency\n- **Regression Tests**: Display stacking prevention, layout overflow protection\n\n### Quality Metrics\n- **Overall Quality Score**: 96/100 (automated validation)\n- **Test Coverage**: 95%+ across all components\n- **Performance**: Sub-microsecond operations, minimal memory overhead\n- **Security**: Zero vulnerabilities, comprehensive threat coverage\n- **Compatibility**: 100% backward compatibility, universal terminal support\n\n## 🛠️ Development\n\n### Build and Test\n\n```bash\n# Development build\ngo build -o cce .\n\n# Run comprehensive test suite\nmake test # or: go test -v ./...\nmake test-coverage # HTML coverage report\nmake test-security # Security-specific tests\nmake bench # Performance benchmarks\n\n# Code quality\nmake quality # fmt + vet + test\nmake fmt # Format code\nmake vet # Static analysis\n```\n\n### Project Structure\n\n```\n├── main.go # CLI interface and flag passthrough system\n├── config.go # Configuration management with atomic operations\n├── ui.go # ANSI-free display management and responsive UI\n├── launcher.go # Process execution with argument forwarding\n├── go.mod # Go module definition\n├── go.sum # Dependency checksums\n├── CLAUDE.md # Development documentation\n├── README.md # User documentation\n└── Tests:\n ├── *_test.go # Comprehensive unit tests\n ├── integration_test.go # End-to-end workflows\n ├── security_test.go # Security validation\n ├── terminal_display_fix_test.go # Display management\n ├── ui_layout_test.go # Responsive layout\n └── display_stacking_fix_test.go # Navigation behavior\n```\n\n## 📋 Requirements\n\n- **Go 1.21+** (for building from source)\n- **Claude Code CLI** must be installed and available in PATH as `claude`\n- **Terminal**: Any terminal emulator (ANSI support optional but enhanced)\n\n## 🚀 Migration Guide\n\n### From Previous Versions\nThis enhanced version maintains full backward compatibility. Existing configuration files in `~/.claude-code-env/config.json` work immediately without modification.\n\n### New Features Available\n- **Additional Environment Variables**: Configure custom environment variables like `ANTHROPIC_SMALL_FAST_MODEL`\n- **Flag Passthrough**: Start using `cce -r`, `cce --help`, etc.\n- **Enhanced UI**: Enjoy responsive design and clean navigation\n- **Universal Compatibility**: Works consistently across all terminal types\n- **Enhanced Security**: Benefit from command injection prevention\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make changes following KISS principles and existing patterns\n4. Add comprehensive tests for new functionality\n5. Run `make test` to ensure all tests pass\n6. Run `make quality` for code quality checks\n7. Submit a pull request with detailed description\n\n### Development Principles\n1. **KISS Principle**: Simple, direct implementations\n2. **Security First**: All operations must be secure by design\n3. **Universal Compatibility**: Features must work across all platforms\n4. **Comprehensive Testing**: 95%+ test coverage required\n5. **Performance Focus**: Sub-microsecond operations preferred\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- Built with **Claude Code** integration\n- Powered by **Go standard library** + `golang.org/x/term`\n- Designed with **KISS principles** and **universal compatibility**\n- Tested across **multiple platforms** and **terminal environments**\n\n---\n\n**Claude Code Environment Switcher**: Production-ready, secure, and universally compatible CLI tool for managing Claude Code environments with transparent flag passthrough and intelligent display management.\n"}}}} |