ccconfig 1.1.0 → 1.3.0

package/README.md

@@ -1,5 +1,7 @@
 # Claude Code Configuration Manager
 
+[English](README.md) | [中文](README_zh.md)
+
 Quickly switch between different claude-code providers
 
 
@@ -9,6 +11,9 @@ ccconfig use company
 
 # Switch back to personal configuration after work
 ccconfig use personal
+
+# Permanently write to shell config (no need to eval or source each time)
+ccconfig use personal --permanent  # or use -p for short
 ```
 
 ## Quick Start
@@ -32,24 +37,46 @@ ccconfig add
 # - ANTHROPIC_BASE_URL
 # - ANTHROPIC_AUTH_TOKEN
 # - ANTHROPIC_API_KEY
-# - Description
+# - ANTHROPIC_MODEL (optional)
+# - ANTHROPIC_SMALL_FAST_MODEL (optional)
 
 # 3. Switch configuration
 ccconfig use work
 
-# 4. Restart Shell or apply immediately
+# 4. Apply immediately (choose one method):
+# Method A: Temporary (only in current shell)
 eval $(ccconfig env bash)  # or use the detected command from output
+
+# Method B: Permanent (write to shell config file)
+ccconfig use work --permanent  # or -p for short
+# Automatically detects and modifies ~/.bashrc, ~/.zshrc, or config.fish
 ```
 
 ### Settings Mode
 
+Settings Mode directly modifies `~/.claude/settings.json` file, which is Claude Code's native configuration file. This mode is suitable when you don't want to configure shell scripts.
+
+**How it works:**
+- Writes environment variables directly into `~/.claude/settings.json` under the `env` field
+- Claude Code reads these settings on startup
+- No shell configuration required
+- Requires Claude Code restart after each switch
+
+**Setup:**
+
 ```bash
 # 1. Switch to settings mode
 ccconfig mode settings
 
 # 2. Add configuration (interactive mode)
 ccconfig add
-# Follow the prompts to configure
+# Follow the prompts to enter:
+# - Name
+# - ANTHROPIC_BASE_URL
+# - ANTHROPIC_AUTH_TOKEN
+# - ANTHROPIC_API_KEY
+# - ANTHROPIC_MODEL (optional)
+# - ANTHROPIC_SMALL_FAST_MODEL (optional)
 
 # 3. Switch configuration
 ccconfig use work
@@ -58,9 +85,52 @@ ccconfig use work
 # Configuration is now active!
 ```
 
+**Verification:**
+```bash
+# Check current configuration
+ccconfig current
+
+# View the settings file directly
+cat ~/.claude/settings.json
+```
+
 #### ENV Mode Shell Configuration
 
-Configure once by adding to your Shell startup files:
+You have two options to configure shell environment:
+
+**Option 1: Automatic (Recommended)**
+
+Use the `-p/--permanent` flag to automatically write to your shell config:
+
+```bash
+# Automatically detects your shell and writes to the appropriate config file
+ccconfig use <profile> --permanent
+
+# You will be prompted with:
+# - Warning about modifying shell config
+# - Target file path
+# - Content preview
+# - Confirmation prompt (yes/no)
+
+# This will modify:
+# - Fish: ~/.config/fish/config.fish
+# - Bash: ~/.bashrc
+# - Zsh: ~/.zshrc
+# - PowerShell: ~/.config/powershell/profile.ps1
+```
+
+The tool will add a marked block between `# >>> ccconfig >>>` and `# <<< ccconfig <<<` markers, making it easy to identify and update later.
+
+**Safety Features:**
+- **User confirmation required**: You will be prompted before any file is modified
+- **Content preview**: Shows exactly what will be written
+- **Clear explanation**: Explains what changes will be made
+- **Non-destructive**: Existing content is preserved, only the ccconfig block is updated
+- **Interactive only**: Requires interactive terminal to prevent accidental modifications
+
+**Option 2: Manual Configuration**
+
+If you prefer to manually configure, add the following to your shell startup files:
 
 **Fish** (`~/.config/fish/config.fish`):
 ```fish
@@ -68,8 +138,10 @@ Configure once by adding to your Shell startup files:
 set -l ccconfig_env ~/.config/ccconfig/current.env
 if test -f $ccconfig_env
     for line in (cat $ccconfig_env)
-        set -l parts (string split '=' $line)
-        set -gx $parts[1] $parts[2]
+        set -l parts (string split -m1 '=' $line)
+        if test (count $parts) -eq 2
+            set -gx $parts[1] $parts[2]
+        end
     end
 end
 ```
@@ -78,7 +150,9 @@ end
 ```bash
 # Load Claude Code environment variables
 if [ -f ~/.config/ccconfig/current.env ]; then
-    export $(grep -v '^#' ~/.config/ccconfig/current.env | xargs)
+    set -a
+    . ~/.config/ccconfig/current.env
+    set +a
 fi
 ```
 
@@ -86,7 +160,9 @@ fi
 ```zsh
 # Load Claude Code environment variables
 if [ -f ~/.config/ccconfig/current.env ]; then
-    export $(grep -v '^#' ~/.config/ccconfig/current.env | xargs)
+    set -a
+    . ~/.config/ccconfig/current.env
+    set +a
 fi
 ```
 
@@ -103,98 +179,95 @@ if (Test-Path $cconfigEnv) {
 }
 ```
 
-## Command Reference
+**Note**: Manual configuration allows you to switch profiles dynamically by changing `current.env`, while `-p/--permanent` writes the values directly into the shell config.
+
+## Advanced Usage
 
-### Basic Commands
+### Update Existing Configuration
+
+If you need to modify an existing configuration, use the `update` command:
 
 ```bash
-# Run without command (defaults to list)
-ccconfig
+# Update a configuration interactively
+ccconfig update work
 
-# List all configurations
-ccconfig list
+# The tool will:
+# 1. Show current values as defaults
+# 2. Prompt for each field
+# 3. Press Enter to keep current value, or type new value to update
+```
 
-# Add new configuration (interactive mode only, auto-creates config file on first use)
-ccconfig add
+**Example:**
+```bash
+$ ccconfig update work
+Updating configuration 'work'
+Press Enter to keep the current value, or enter a new value to update
 
-# Switch configuration
-ccconfig use <name>
+ANTHROPIC_BASE_URL [https://api.company.com]: https://new-api.company.com
+ANTHROPIC_AUTH_TOKEN [sk-ant-api...]: <press Enter to keep>
+ANTHROPIC_API_KEY []: sk-new-key-123
+ANTHROPIC_MODEL [claude-sonnet-4-5-20250929]: <press Enter to keep>
+Do you want to set ANTHROPIC_SMALL_FAST_MODEL? (y/N) [n]:
 
-# Remove configuration
-ccconfig remove <name>
+✓ Configuration 'work' updated
+```
 
-# View current status (shows all configuration sources)
-ccconfig current
-ccconfig current --show-secret  # Show full token
+**Note:** After updating a configuration, remember to activate it with `ccconfig use work` if you want the changes to take effect immediately.
 
-# Show configuration file path
-ccconfig edit
+### Shell Completion
 
-# View version
-ccconfig --version  # or -V
-```
+ccconfig supports shell completion for commands, profile names, and options. This makes it easier to discover and use commands.
 
-### Mode Management
+**Features:**
+- ✅ Command completion (list, add, update, use, remove, etc.)
+- ✅ Profile name completion (dynamically reads from your configurations)
+- ✅ Option completion (--permanent, --show-secret, etc.)
+- ✅ Mode completion (settings, env)
+- ✅ Format completion (bash, zsh, fish, etc.)
+
+**Installation:**
 
 ```bash
-# View current mode
-ccconfig mode
+# Bash
+ccconfig completion bash >> ~/.bashrc
+source ~/.bashrc
 
-# Switch to settings mode
-ccconfig mode settings
+# Zsh
+ccconfig completion zsh >> ~/.zshrc
+source ~/.zshrc
 
-# Switch to env mode
-ccconfig mode env
+# Fish
+ccconfig completion fish > ~/.config/fish/completions/ccconfig.fish
+# Fish will automatically load it on next startup
+
+# PowerShell
+ccconfig completion pwsh >> $PROFILE
+# Reload profile: . $PROFILE
 ```
 
-### ENV Mode Specific
+**Note for PowerShell:** If you get an error about `$PROFILE` not existing, create it first:
+```powershell
+New-Item -Path $PROFILE -ItemType File -Force
+ccconfig completion pwsh >> $PROFILE
+. $PROFILE
+```
+
+**Usage examples after installing completion:**
 
 ```bash
-# Apply immediately in current Shell (env mode)
-eval $(ccconfig env bash)      # Bash/Zsh
-ccconfig env fish | source     # Fish
-ccconfig env pwsh | iex        # PowerShell
+# Type 'ccconfig' and press TAB to see all commands
+ccconfig <TAB>
+# Shows: list, add, update, use, remove, current, mode, env, edit, completion
 
-# Output .env format
-ccconfig env dotenv > .env
-```
+# Type 'ccconfig use' and press TAB to see all profiles
+ccconfig use <TAB>
+# Shows: work, personal, project1, etc.
 
-## Configuration File Locations
-
-- **Configuration List**: `~/.config/ccconfig/profiles.json`
-- **Claude Settings**: `~/.claude/settings.json`
-- **Environment Variables File**: `~/.config/ccconfig/current.env`
-- **Mode Settings**: `~/.config/ccconfig/mode`
-
-## Configuration Example
-
-`~/.config/ccconfig/profiles.json`:
-
-```json
-{
-  "profiles": {
-    "work": {
-      "env": {
-        "ANTHROPIC_BASE_URL": "https://api-proxy.company.com",
-        "ANTHROPIC_AUTH_TOKEN": "sk-auth-work-xxxxx",
-        "ANTHROPIC_API_KEY": "sk-key-work-xxxxx"
-      },
-      "description": "Work account"
-    },
-    "personal": {
-      "env": {
-        "ANTHROPIC_BASE_URL": "https://api.anthropic.com",
-        "ANTHROPIC_AUTH_TOKEN": "sk-ant-personal-xxxxx",
-        "ANTHROPIC_API_KEY": "sk-ant-personal-xxxxx"
-      },
-      "description": "Personal account"
-    }
-  }
-}
+# Type 'ccconfig mode' and press TAB
+ccconfig mode <TAB>
+# Shows: settings, env
 ```
 
-## Advanced Usage
-
 ### Quick Aliases
 
 ```bash
@@ -246,15 +319,56 @@ git commit -m "ccconfig profiles"
 ### Configuration Not Taking Effect
 
 **Settings Mode**:
-1. Check if configuration is written correctly: `ccconfig current`
-2. Confirm Claude Code has been restarted
-3. Check the `env` field in `~/.claude/settings.json`
+1. **Check configuration is written correctly**: 
+   ```bash
+   ccconfig current
+   # Look at section 【1】~/.claude/settings.json
+   ```
+2. **Verify settings.json directly**:
+   ```bash
+   cat ~/.claude/settings.json | grep -A 5 '"env"'
+   ```
+3. **Confirm Claude Code has been restarted**:
+   - Completely quit Claude Code (not just close window)
+   - Restart the application
+4. **Check the `env` field** in `~/.claude/settings.json`:
+   ```json
+   {
+     "env": {
+       "ANTHROPIC_BASE_URL": "https://api.anthropic.com",
+       "ANTHROPIC_AUTH_TOKEN": "sk-...",
+       "ANTHROPIC_API_KEY": "sk-..."
+     }
+   }
+   ```
 
 **ENV Mode**:
-1. Check environment variables file: `cat ~/.config/ccconfig/current.env`
-2. Confirm Shell configuration is correct: `cat ~/.bashrc | grep ccconfig`
-3. Restart Shell or use `eval $(ccconfig env bash)`
-4. Check process environment variables: `ccconfig current`
+1. **Check environment variables file**: 
+   ```bash
+   cat ~/.config/ccconfig/current.env
+   ```
+2. **If using --permanent flag**:
+   - The tool will show a warning and ask for confirmation before modifying files
+   - Check your shell config file has ccconfig block:
+     ```bash
+     # For bash/zsh
+     cat ~/.bashrc | grep -A 5 "ccconfig"
+     # For fish
+     cat ~/.config/fish/config.fish | grep -A 5 "ccconfig"
+     ```
+   - Restart shell or run: `source ~/.bashrc` (or equivalent for your shell)
+   - Note: You can also use `-p` as a short form of `--permanent`
+   - To cancel the operation, type "no" when prompted
+   
+3. **If using manual configuration or eval command**:
+   - Confirm Shell configuration is correct: `cat ~/.bashrc | grep ccconfig`
+   - Restart Shell or use `eval $(ccconfig env bash)`
+   
+4. **Check process environment variables**: 
+   ```bash
+   ccconfig current
+   # Look at section 【3】Current Process Environment Variables
+   ```
 
 ### Configuration Lost After Mode Switch
 
@@ -287,82 +401,6 @@ chmod 600 ~/.config/ccconfig/current.env
 
 4. **Version Control**: If version controlling configurations, use encryption or private repositories
 
-## Frequently Asked Questions
-
-**Q: Which is better, Settings mode or ENV mode?**
-
-A:
-- **ENV mode** is recommended (default, better cross-shell support, instant apply)
-- If you prefer not to configure shell startup files, **Settings mode** can be simpler (only needs Claude Code restart)
-
-**Q: Can I use both modes simultaneously?**
-
-A: Not recommended. Claude Code reads configuration based on priority:
-- Settings mode: Reads directly from `settings.json`
-- ENV mode: Reads from environment variables
-
-Using both simultaneously may cause confusion.
-
-**Q: How to use on Windows?**
-
-A: Fully supported on Windows:
-- Configuration file location: `%USERPROFILE%\.config\ccconfig\`
-- Settings mode requires no additional configuration
-- ENV mode uses PowerShell configuration
-
-**Q: Do I need to restart after switching configurations?**
-
-A:
-- **Settings mode**: Need to restart Claude Code
-- **ENV mode**: Need to restart Shell (or use `env` command for immediate effect)
-
-**Q: Can I export configurations for team use?**
-
-A: Yes, but be careful:
-```bash
-# Export configuration structure (excluding API keys)
-cat ~/.config/ccconfig/profiles.json | \
-  jq '.profiles | map_values({baseUrl, description})' > team-config.json
-
-# Team members manually add their own API keys after importing
-```
-
-## Development
-
-### Project Structure
-
-```
-.
-├── ccconfig.js         # Core script
-├── package.json             # npm configuration
-├── README.md                # This document
-└── .gitignore               # Git ignore file
-```
-
-### Testing
-
-```bash
-# Test version output
-node ccconfig.js --version
-
-# Test adding configuration (interactive only)
-node ccconfig.js add
-
-# Test listing
-node ccconfig.js list
-
-# Test switching
-node ccconfig.js use test
-
-# Test status viewing
-node ccconfig.js current
-node ccconfig.js current --show-secret
-
-# Test mode switching
-node ccconfig.js mode
-node ccconfig.js mode env
-```
-
 ## License
 
 MIT