cursor-synchronizer

A small CLI that one-way syncs your project's .cursor/ rules, skills, and commands from a remote git repository so every developer on the team works with the same Cursor agent context.

• Single static binary (Go, no runtime dependencies).
• Simple model: .cursor-sync/config.yaml records the remote; .cursor-sync/manifest.yaml records which entries were pulled.
• One-way pull only. Files you add yourself under .cursor/ are never touched by cursor-sync.

Install

Clone the repo and run the installer for your OS. No network access is required once the repo is cloned:

git clone https://github.com/cwang0126/cursor-synchronizer.git
cd cursor-synchronizer

# macOS / Linux
./install.sh

# Windows (PowerShell)
.\install.ps1

The installer copies the prebuilt binary from bin/<os>_<arch>/ into /usr/local/bin (or ~/.local/bin as a fallback) — or %USERPROFILE%\.cursor-sync\bin on Windows — and makes sure it's on your PATH.

Building prebuilt binaries

If your OS/architecture isn't already in bin/, build it first with the interactive helper (requires Go 1.22+):

./build.sh        # pick a target or "all"
./install.sh      # then install

build.sh writes to bin/<os>_<arch>/cursor-sync[.exe], matching what install.sh / install.ps1 look for.

Build from source

Requires Go 1.22+.

git clone https://github.com/cwang0126/cursor-synchronizer.git
cd cursor-synchronizer
go build -ldflags="-s -w" -o cursor-sync .
./cursor-sync --help

To use cursor-sync from any project directory, install the freshly built binary somewhere on your PATH:

# Preferred: user-local, no sudo required.
mkdir -p "$HOME/.local/bin"
install -m 0755 cursor-sync "$HOME/.local/bin/cursor-sync"

# If ~/.local/bin isn't on your PATH yet, add it (zsh shown):
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
exec $SHELL -l

# Verify:
which cursor-sync
cursor-sync --help

Prefer a system-wide install? Use sudo install -m 0755 cursor-sync /usr/local/bin/cursor-sync instead.

Usage

cursor-sync clone <repo-url> [directory]

Shallow-clones the remote, lets you multi-select which rules/, skills/, and commands/ entries to import, then writes them under <directory>/.cursor/ (defaulting to the current folder). It also creates <directory>/.cursor-sync/config.yaml and manifest.yaml.

# Into the current directory:
cursor-sync clone https://github.com/example/cursor-config.git

# Into a new subdirectory:
cursor-sync clone https://github.com/example/cursor-config.git my-project

# Skip the prompt and import everything:
cursor-sync clone --all https://github.com/example/cursor-config.git

# Use a non-default(main/master) branch:
cursor-sync clone --branch dev https://github.com/example/cursor-config.git

# Read the source from a custom folder on the remote (default: auto-detect
# .cursor/, cursor/, or repo root):
cursor-sync clone --folder configs/cursor https://github.com/example/cursor-config.git

The multi-select prompt uses arrow keys to navigate, space to toggle, and Enter to confirm. The first option, [Select All], picks everything.

cursor-sync pull [--yes]

Re-syncs only the entries previously listed in .cursor-sync/manifest.yaml. On per-file conflicts you'll be asked:

Overwrite rules/foo.mdc? [y/N/a/s]

• y overwrite this file
• N keep local (default)
• a overwrite all remaining conflicts
• s skip all remaining conflicts

--yes (-y) overwrites everything without prompting.

--folder (-f) overrides the remote source folder for this pull and writes the new value back into .cursor-sync/config.yaml so later pulls use it by default.

cursor-sync list

Lists every entry under .cursor/ and tags each one:

• [remote] — name appears in the manifest, pulled from the remote
• [local] — added by you, not tracked by cursor-sync

This is offline; no network call is made.

cursor-sync config

cursor-sync config --show remote
cursor-sync config --set remote https://github.com/example/cursor-config.git
cursor-sync config --set branch dev
cursor-sync config --set folder configs/cursor

How it works

your-project/
├── .cursor/                 # synced (rules/, skills/, commands/)
└── .cursor-sync/
    ├── config.yaml          # remote URL + branch
    └── manifest.yaml        # files pulled from the remote

cursor-sync shells out to your local git binary to do a --depth 1 clone into a temp directory, copies just the entries you selected, then deletes the temp clone. Authentication uses your existing git credentials (SSH keys, gh auth, ~/.gitconfig, etc.); cursor-sync itself stores no secrets.

Supported remote layouts

By default the remote repo's source layout is auto-detected. Detection runs in this order and picks the first match:

<repo>/.cursor/{rules,skills,commands}/   # preferred
<repo>/cursor/{rules,skills,commands}/
<repo>/{rules,skills,commands}/           # groupings at the repo root

If your remote keeps the groupings somewhere else, pass --folder <path> (relative to the repo root) on clone / pull, or persist it with cursor-sync config --set folder <path>. For example:

--folder configs/cursor   # <repo>/configs/cursor/{rules,skills,commands}/

Regardless of the remote layout, files always land locally under <project>/.cursor/ because that's what Cursor itself reads.

License

MIT