cfgmod

A CLI tool for switching JSON/TOML configuration files. Define configuration profiles and switch between them with a single command.

Installation

npm install -g cfgmod

Or run directly with npx:

npx cfgmod <command>

Quick Start

1. Create a configuration file at ~/.cfgmod/cfgmod.json:

{
  "variables": {
    "DB_HOST": "localhost"
  },
  "profiles": {
    "dev": {
      "targets": [
        {
          "files": ["~/.config/myapp/config.json"],
          "config": {
            "database": {
              "host": "${DB_HOST}",
              "port": 5432
            }
          }
        }
      ]
    },
    "prod": {
      "targets": [
        {
          "files": ["~/.config/myapp/config.json"],
          "config": {
            "database": {
              "host": "prod-db.example.com",
              "port": 5432
            }
          }
        }
      ]
    }
  }
}

2. Switch to a profile:

cfgmod use dev

Commands

cfgmod use <profile>

Switch to a configuration profile.

cfgmod use dev
cfgmod use prod --dry-run  # Preview changes without modifying files
cfgmod use prod --force    # Force apply even if current config is unknown

cfgmod reload <profile>

Force switch to a profile, skipping the current config check. This is an alias for cfgmod use <profile> --force.

cfgmod reload dev

cfgmod list

List all available profiles.

cfgmod list

Output:

Profiles:

● dev (current)
    → ~/.config/myapp/config.json

○ prod
    → ~/.config/myapp/config.json

cfgmod current

Show the currently active profile.

cfgmod current

Global Options

Option	Environment Variable	Description
-c, --config <path>	CFGMOD_CONFIG	Path to cfgmod.json
--dry-run	-	Preview changes without modifying files
-y, --force	-	Force apply changes even if current config is unknown

Configuration File

Location

By default, cfgmod looks for configuration at ~/.cfgmod/cfgmod.json. You can override this with:

• CLI option: --config /path/to/cfgmod.json
• Environment variable: CFGMOD_CONFIG=/path/to/cfgmod.json

Structure

{
  "variables": {
    "VAR_NAME": "value",
    "FROM_ENV": "${env:ENV_VAR_NAME}"
  },
  "profiles": {
    "profile-name": {
      "targets": [
        {
          "files": ["path/to/config.json", "path/to/another.toml"],
          "config": {
            "nested": {
              "key": "value"
            }
          }
        }
      ]
    }
  }
}

Variables

Define reusable values in the variables section:

{
  "variables": {
    "API_HOST": "api.example.com",
    "API_KEY": "${env:MY_API_KEY}"
  },
  "profiles": {
    "dev": {
      "targets": [
        {
          "files": ["config.json"],
          "config": {
            "api": {
              "host": "${API_HOST}",
              "key": "${API_KEY}"
            }
          }
        }
      ]
    }
  }
}

• ${VAR_NAME} - Reference a variable defined in variables
• ${env:ENV_VAR_NAME} - Reference an environment variable

Wildcards

Use wildcards to apply the same value to multiple keys:

{
  "profiles": {
    "local": {
      "targets": [
        {
          "files": ["servers.json"],
          "config": {
            "servers": {
              "*": {
                "host": "localhost"
              }
            }
          }
        }
      ]
    }
  }
}

Given a target file:

{
  "servers": {
    "web": { "host": "web.example.com", "port": 80 },
    "api": { "host": "api.example.com", "port": 8080 },
    "db": { "host": "db.example.com", "port": 5432 }
  }
}

After cfgmod use local:

{
  "servers": {
    "web": { "host": "localhost", "port": 80 },
    "api": { "host": "localhost", "port": 8080 },
    "db": { "host": "localhost", "port": 5432 }
  }
}

Both * and $wildcard are supported as wildcard keys.

Multiple Targets

A single profile can modify multiple files with different configurations:

{
  "profiles": {
    "dev": {
      "targets": [
        {
          "files": ["~/.config/app-a/config.json"],
          "config": {
            "database": { "host": "localhost" }
          }
        },
        {
          "files": ["~/.config/app-b/settings.toml"],
          "config": {
            "api": { "endpoint": "http://localhost:3000" }
          }
        }
      ]
    }
  }
}

Multiple Files with Same Config

Apply the same configuration to multiple files (files must have the same structure):

{
  "profiles": {
    "dev": {
      "targets": [
        {
          "files": [
            "~/.config/instance-1/config.json",
            "~/.config/instance-2/config.json"
          ],
          "config": {
            "server": { "host": "localhost" }
          }
        }
      ]
    }
  }
}

Examples

Switching Claude Code API Endpoints

Use cfgmod to switch between different API providers for Claude Code:

{
  "variables": {
    "OFFICIAL_URL": "https://api.anthropic.com",
    "OFFICIAL_TOKEN": "${env:ANTHROPIC_API_KEY}",
    "PROXY_URL": "https://your-proxy.example.com",
    "PROXY_TOKEN": "${env:PROXY_API_KEY}"
  },
  "profiles": {
    "official": {
      "targets": [
        {
          "files": ["~/.claude/settings.json"],
          "config": {
            "env": {
              "ANTHROPIC_BASE_URL": "${OFFICIAL_URL}",
              "ANTHROPIC_AUTH_TOKEN": "${OFFICIAL_TOKEN}"
            }
          }
        }
      ]
    },
    "proxy": {
      "targets": [
        {
          "files": ["~/.claude/settings.json"],
          "config": {
            "env": {
              "ANTHROPIC_BASE_URL": "${PROXY_URL}",
              "ANTHROPIC_AUTH_TOKEN": "${PROXY_TOKEN}"
            }
          }
        }
      ]
    }
  }
}

Switch to official API:

cfgmod use official

Switch to proxy:

cfgmod use proxy

Preview changes before applying:

cfgmod use proxy --dry-run

Supported File Types

• JSON (.json)
• TOML (.toml)

Error Handling

Scenario	Behavior
cfgmod.json not found	Error with instructions
Target file not found	Error
Profile not found	Error with available profiles
Current config doesn't match any profile	Warning, use --force to override
Variable not defined	Error
Environment variable not set	Error

License

MIT