config-cli

config-cli 是一个用于管理本机 ~/.config 配置的命令行工具。它可以扫描配置项、交互选择需要管理的配置、上传到 GitHub 仓库，并在另一台机器上从 GitHub 下载后恢复。

功能

• 扫描 ~/.config 顶层文件和目录。
• 交互式选择要上传或下载的配置。
• 使用单个 GitHub 仓库保存所有配置。
• 使用 manifest.json 记录配置元数据。
• 下载恢复前自动备份本机已有配置。
• 拒绝 manifest 中的绝对路径和路径穿越，避免覆盖 ~/.config 之外的文件。

环境要求

• Node.js >=20.11
• pnpm
• git
• GitHub CLI：gh

上传前需要先登录 GitHub CLI：

gh auth login
gh auth status

快速开始

1. 设置默认 GitHub 配置仓库：

config-cli repo set git@github.com:<user>/<repo>.git

2. 扫描并保存最近选择：

config-cli scan

3. 上传本机配置：

config-cli upload

4. 在另一台机器上设置同一个仓库并下载：

config-cli repo set git@github.com:<user>/<repo>.git
config-cli download

也可以不设置默认仓库，直接传入仓库 URL：

config-cli upload git@github.com:<user>/<repo>.git
config-cli download git@github.com:<user>/<repo>.git

命令说明

config-cli scan

扫描 ~/.config 下的顶层文件和目录，弹出多选列表，并把本次选择保存为最近选择。

config-cli scan

说明：

• 只扫描 ~/.config 的第一层。
• 会跳过 ~/.config/config-cli，避免把工具自身状态上传。
• 不会修改 GitHub 仓库，也不会覆盖本地配置。

config-cli upload [repo]

选择本机 ~/.config 下的配置并上传到 GitHub 仓库。

config-cli upload
config-cli upload git@github.com:<user>/<repo>.git

行为：

• 先检查 gh auth status。
• 交互选择要上传的配置。
• clone 目标仓库到临时目录。
• 将选中的配置写入仓库的 configs/ 目录。
• 生成或更新 manifest.json。
• 执行 git add、git commit、git push。
• 上传成功后保存默认仓库 URL 和最近选择。

如果不传 repo，CLI 会提示输入已有仓库 URL，或通过 gh repo create 创建新的私有仓库。

config-cli download [repo]

从 GitHub 仓库拉取配置，交互选择要恢复的配置项。

config-cli download
config-cli download git@github.com:<user>/<repo>.git

仓库来源优先级：

1. 命令行传入的 [repo]
2. config-cli repo set <url> 保存的默认仓库

恢复行为：

• clone 仓库到临时目录。
• 读取并校验 manifest.json。
• 选择要恢复的配置。
• 如果本机目标路径已存在，先备份到 ~/.config/config-cli/backups/<timestamp>/<name>。
• 再把远端配置复制到 ~/.config/<name>。

config-cli repo set <url>

保存默认 GitHub 仓库 URL。

config-cli repo set git@github.com:<user>/<repo>.git

默认仓库会写入：

~/.config/config-cli/config.json

config-cli repo get

查看当前保存的默认 GitHub 仓库 URL。

config-cli repo get

GitHub 仓库结构

上传后的仓库结构如下：

.
├── configs
│   ├── nvim
│   │   └── init.lua
│   └── starship.toml
└── manifest.json

configs/<name> 对应本机：

~/.config/<name>

manifest.json 示例：

{
  "version": 1,
  "generatedAt": "2026-04-30T00:00:00.000Z",
  "entries": [
    {
      "name": "nvim",
      "relativePath": "nvim",
      "kind": "directory",
      "updatedAt": "2026-04-30T00:00:00.000Z",
      "fileCount": 12,
      "sourceHost": "my-mac"
    }
  ]
}

本地状态与备份

工具自身配置保存位置：

~/.config/config-cli/config.json

下载恢复时的备份位置：

~/.config/config-cli/backups/<timestamp>/<name>

例如恢复 nvim 时，如果本机已有 ~/.config/nvim，会先备份到：

~/.config/config-cli/backups/2026-04-30T12-00-00-000Z/nvim

安全边界

v1 只管理 ~/.config 下的顶层配置，不处理：

• ~/.zshrc
• ~/.ssh
• ~/.gitconfig
• 其他 home 根目录 dotfiles

下载时会校验 manifest 中的路径：

• 拒绝绝对路径。
• 拒绝 .. 路径穿越。
• 只恢复到 ~/.config/<relativePath>。

常见问题

上传时报错 GitHub CLI 未登录

先登录 GitHub CLI：

gh auth login

下载时报错没有默认仓库

先设置默认仓库，或直接给 download 传入仓库 URL：

config-cli repo set git@github.com:<user>/<repo>.git
config-cli download

想恢复下载前的本地配置

查看本次恢复输出中的 backup 路径，或进入备份目录手动复制回来：

ls ~/.config/config-cli/backups

仓库内容没有变化

如果上传的配置与远端一致，CLI 不会创建新的 commit。

质量检查

pnpm run lint
pnpm run typecheck
pnpm run test
pnpm run build