custom-cmd

custom-cmd 是一个零依赖、可跨终端复用的命令别名管理器。你可以用极短的别名映射任意长命令，在任何 Shell 中输入别名即可执行。所有数据默认存放在 Windows 的 C:\ProgramData\custom-cmd（或类 Unix 系统的 ~/.custom-cmd）下，升级 Node 或更换终端都不会丢失。

安装

pnpm add -g @drmrkj/custom-cmd
# 或 npm install -g @drmrkj/custom-cmd
# 或 yarn global add @drmrkj/custom-cmd

安装后，只要你能在终端里运行 custom-cmd，工具就会自动在同一可执行目录（即当前已经在 PATH 中的目录）为每个别名生成脚本，并同步写入 C:\ProgramData\custom-cmd\bin。因此无需另外配置 pnpm bin -g / npm bin -g 等路径，仅在希望其它终端也能找到这些脚本时，才需要把 C:\ProgramData\custom-cmd\bin（可选）手动加入 PATH。

快速上手

custom-cmd group create frontend
custom-cmd group use frontend
custom-cmd add d pnpm run dev
custom-cmd add gpu "git pull upstream"
custom-cmd edit d pd     # 将别名 d 重命名为 pd

d        # 立即执行 pnpm run dev
gpu d    # 依次展开为 "git pull upstream pnpm run dev"
gpu dev  # 如果 dev 没有别名，则保持原样 => git pull upstream dev
pd       # 重命名后仍然执行 pnpm run dev

组与迁移

custom-cmd 现在以“组”为最小作用域：

• 每个命令都必须挂在某个组下，命令的增删改查全部作用于当前激活组。使用 custom-cmd group list 可以查看所有组，custom-cmd group use <name> 用于切换，首次使用时记得 group create。
• 删除组时若仍包含命令，会先列出该组的别名并要求输入 y/yes 确认，避免误删。如果你确信要删除，可以追加 --force 跳过确认。
• 运行 custom-cmd config path 可查看 commands.json 所在目录，custom-cmd config open 会在系统文件管理器中直接打开，方便手动备份。
• 迁移/备份推荐使用 custom-cmd export <file>（导出全部组）或 custom-cmd export <file> --group <name>（仅导出指定组）。在目标环境执行 custom-cmd import <file> 即可创建对应的组和命令；若发现同名组会列出冲突并提示是否覆盖，拒绝则终止导入，确认后会先删除旧组再写入新数据。

功能说明

| 命令 | 作用 | | --- | --- | | custom-cmd group create <name> | 创建一个新的命令组，第一次创建会自动成为当前组。 | | custom-cmd group list | 查看现有组，并使用 * 标记当前激活的组。 | | custom-cmd group use <name> | 切换当前激活的组，所有命令操作都会针对该组生效。 | | custom-cmd group remove <name> [--force] | 删除指定组；若组内仍有命令会列出并要求确认。 | | custom-cmd add <alias> <command...> | 在当前组创建或更新别名，命令可包含空格。 | | custom-cmd edit <old> <new> | 在当前组内重命名别名，映射的命令保持不变。 | | custom-cmd list | 查看当前组的别名列表。 | | custom-cmd remove <alias> | 从当前组删除别名，若其他组不再使用该别名会同步移除脚本。 | | custom-cmd exec <alias> [args...] | 在当前组上下文执行别名，并尝试解析后续参数是否也是别名。 | | custom-cmd config path|open | 打印或打开 commands.json 所在目录，便于手动迁移。 | | custom-cmd export <file> [--group <name>] | 导出全部组或单个组为 JSON，用于备份或迁移。 | | custom-cmd import <file> | 导入 JSON；若发现同名组会报错并指出冲突。 | | custom-cmd --help | 查看帮助信息。 | | custom-cmd --version | 查看当前版本。 |

当你首次创建别名时，custom-cmd 会自动在全局包管理器的 bin 目录以及 C:\ProgramData\custom-cmd\bin 下生成同名可执行脚本，这些脚本内部直接调用 custom-cmd 的实际入口文件，因此今后只需输入别名即可，无需再依赖包管理器的 PATH 设置。

数据位置

C:\ProgramData\custom-cmd
├─ commands.json   # 记录 group => alias => command 的映射以及当前组
└─ bin\            # 存放为每个别名生成的启动脚本

非 Windows 平台会改为 ~/.custom-cmd，结构完全一致。

常见问题

• 别名不合法：只允许字母/数字/中划线/下划线，且内置命令（add/list/remove/exec 等）不可复用。
• 找不到脚本：确认 C:\ProgramData\custom-cmd\bin 或 which custom-cmd / where custom-cmd 输出的目录在当前终端的 PATH 中，并重新打开终端。
• 提示 No active group：使用 custom-cmd group list 检查是否已有组，若没有可以 custom-cmd group create <name> 再 custom-cmd group use <name>。
• 执行时提示 custom-cmd 未找到：升级到最新版本后重新创建别名，新的脚本会直接调用 CLI 的绝对路径，不会再依赖环境变量。
• 命令执行失败：custom-cmd 最终只是把展开后的字符串交给 Shell，建议把最终语句拷贝出来单独测试。
• 导入 JSON 报冲突：说明要导入的组名本地已存在，或者 JSON 内部结构被手动改坏。请先删除冲突组或修改 JSON，再重新执行 custom-cmd import。

开发脚本

pnpm install
pnpm run lint
pnpm run format:check
pnpm run typecheck
pnpm run test
pnpm run build

项目基于 TypeScript + tsup 构建，输出 CommonJS 产物，兼容 Node.js 12 及以上版本。