cfgmod: Instructions file for Claude Code

cfgmod

A CLI tool for switching JSON/TOML configuration files.

Project Overview

cfgmod simplifies configuration switching for tools and applications that use JSON/TOML config files. Users define configuration profiles in cfgmod.json, then switch between them with cfgmod use <profile>.

Tech Stack

• Language: TypeScript
• Runtime: Node.js (>=18.0.0)
• Package Manager: npm
• Build: tsc (TypeScript compiler)

Project Structure

src/
├── index.ts              # CLI entry point (commander-based)
├── types/index.ts        # TypeScript type definitions
├── commands/
│   ├── use.ts            # `cfgmod use <profile>` command
│   ├── list.ts           # `cfgmod list` command
│   └── current.ts        # `cfgmod current` command
├── core/
│   ├── config-loader.ts  # Load and validate cfgmod.json
│   ├── variable-resolver.ts  # Resolve ${VAR} and ${env:VAR}
│   ├── profile-matcher.ts    # Match current config to profiles
│   └── config-applier.ts     # Apply config changes to target files
├── parsers/
│   ├── index.ts          # Unified parser interface
│   ├── json-parser.ts    # JSON read/write
│   └── toml-parser.ts    # TOML read/write
└── utils/
    ├── path.ts           # Path utilities (~ expansion, resolve)
    ├── deep-merge.ts     # Deep merge/clone/compare utilities
    └── wildcard.ts       # Wildcard (* and $wildcard) expansion

Commands

npm run build      # Compile TypeScript to dist/
npm run dev        # Watch mode compilation
npm run test       # Run tests (vitest)
node dist/index.js # Run CLI directly

CLI Usage

cfgmod use <profile>     # Switch to a profile
cfgmod reload <profile>  # Force switch (alias for use --force)
cfgmod list              # List all profiles
cfgmod current           # Show current profile

# Options
--config, -c <path>      # Specify cfgmod.json path
--dry-run                # Preview changes without modifying
--force, -y              # Force apply even if current config unknown