Official docs (fetch live first)
- Fetch https://cursor.com/docs/plugins — especially Test plugins locally.
- Fetch https://cursor.com/docs/reference/plugins — marketplace vs single-plugin layout.
- Follow
plugins/plugin-ops/reference/doc-sources.mdfor the full URL list. - Prefer live docs over this skill if they disagree.
- Melodic policy:
docs/plugin-philosophy.md(skills primary; nocommands/layer for this workflow).
When to use
- Personal / Ultra: disk-truth update path. A personally-added marketplace
(
/plugin marketplace add, formerly/add-plugin) can be pinned with--git-ref, so/plugin marketplace updatewill keep returning the pinned commit. - Any plan where local plugin imports are permitted: local override or offline copy of selected plugins (see step 6 — Enterprise disallows them by default).
- Source can be this Melodic repo, any marketplace URL, or a single-plugin repo.
Inputs
Ask only if missing:
- Source — local path, or git URL (
https://github.com/org/repo). Optional: the script defaults to the repo that contains it, then a short checkout list, thenhttps://github.com/melodic-software/cursor-plugins. - Plugin names (optional) — subset when Source is a multi-plugin marketplace.
- Ref (optional) — branch/tag/SHA for URL sources.
Resolve source — do not search the disk
The hang that made /sync-local look stuck was not the copy. It was
recursive Get-ChildItem / glob / rg under $HOME, OneDrive, Documents, or
AppData. Those walks take minutes on Windows and are forbidden here.
Resolve source with Test-Path / [ -d ] on this list, then stop:
- Open workspace, if it contains
.cursor-plugin/marketplace.jsonor.cursor-plugin/plugin.json. $env:MELODIC_CURSOR_PLUGINS/$MELODIC_CURSOR_PLUGINS, if set and that path exists.- These exact paths, if they exist (no wildcards, no recursion):
D:\repos\github.com\melodic-software\cursor-pluginsC:\repos\github.com\melodic-software\cursor-plugins$HOME/repos/github.com/melodic-software/cursor-plugins$HOME/src/github.com/melodic-software/cursor-plugins$HOME/cursor-plugins
- Else Source is
https://github.com/melodic-software/cursor-plugins(the script clones).
If scripts/sync-local.ps1 / scripts/sync-local.sh are not on disk, clone that
URL to a temp directory and run the script from the clone. Do not invent a
home-directory search to find them.
When Source is a local git checkout, the script fetches and fast-forwards a
clean tracking branch before copying (so a clone that is behind origin is not
what gets installed). A successful fast-forward also runs
git submodule update --init --recursive so a changed gitlink is checked out
before the copy; if that update fails the superproject is reset and the run
copies current HEAD. It does not pull a dirty tree, rebase, or merge
diverged branches — it prints one line and copies HEAD as-is. --dry-run /
-DryRun never updates the source. Pass --no-update / -NoUpdate to skip
the fetch. After a successful update, the same run copies the new tree — do not
pull in a second step and forget to sync.
Steps
- Resolve Source with the list above (path or URL) and optional plugin filter / ref.
- Run from a machine that has the
cursor-pluginsscripts or copy the script invocation into the Source repo if it vendors the same scripts. Prefer Melodic scripts when available:- Windows:
pwsh -File <cursor-plugins>/scripts/sync-local.ps1 [-Source <path-or-url>] [-Plugin a,b] [-Ref main] [-KeepClone] [-NoUpdate] [-DryRun] - Unix:
bash <cursor-plugins>/scripts/sync-local.sh [--dry-run] [--no-update] [--ref main] [--keep-clone] [<path-or-url>] [plugin ...] -Source/ the positional source is optional: both default to the repo containing the script if it looks like a marketplace or plugin, otherwise a short known-checkout list, otherwise they clonehttps://github.com/melodic-software/cursor-plugins.-KeepClone/--keep-clonekeeps the temp clone when the source is a URL (its path is printed at the end) — useful when inspecting what was synced.-NoUpdate/--no-updateskips fetch/fast-forward of a local git checkout.-DryRun/--dry-runwrites nothing, does not update a local git source, and prints[dry-run] <name> -> <dst>per plugin, closing withWould sync (n): ...— a dry run never printsSynced, soSynced (n)in the output is proof a real copy ran. Bash flags are position-independent; PowerShell parameters are named.- A real run against a local git checkout may print one extra stdout line before the per-plugin lines, identical in both twins:
Fast-forwarded <old>..<new>,Local checkout already up to date (<sha>),Local checkout is dirty; syncing the working tree at <sha> without pulling,Local checkout has no upstream; syncing current HEAD <sha>,Could not fetch; syncing current HEAD <sha>, orCould not fast-forward; syncing current HEAD <sha>. None of those is a failure; the copy still runs. - Check the exit code, not just the banner. Both twins exit 1 and copy nothing on: a source path that does not exist (
Source path not found: <path>— plus a stderr hint to pass the Melodic marketplace URL), ametadata.pluginRootthat escapes the source repo (metadata.pluginRoot escapes the source repo: <value>), a plugin filter that excludes the only plugin (Plugin filter excluded single plugin '<name>'), and no plugins resolved — including an emptyplugins/directory or"plugins": [], which exit 1 withNo Cursor plugins found under <path> (need marketplace.json or plugin.json).rather than reporting a hollowSynced (0). The messages are worded identically in both twins; the pwsh twin wraps them in a PowerShell error record, so expect the same sentence surrounded by a stack trace. - Argument errors are twin-specific — do not quote one twin's message or code when running the other.
sync-local.shparses its own flags, so a--refwith no value printsMissing value for --refand exits 2 (an unknown flag printsUnknown flag: <flag>and also exits 2).sync-local.ps1declaresparam([string] $Ref = ""), so PowerShell's own parameter binder rejects the argument before the script body runs:-Refwith nothing after it givesMissing an argument for parameter 'Ref'. Specify a parameter of type 'System.String' and try again.and exits 1, and an unknown-FlaggivesA parameter cannot be found that matches parameter name '<flag>'., also exit 1. The binder emits that code before the script can set one, so the divergence is by design; match the message and code to the twin you actually invoked. - Individual plugins can also be skipped and reported, in both twins:
(source escapes plugin root)when an entry'ssourceresolves outside the plugin root,(invalid plugin name)for a name that is not a single path segment,(missing .cursor-plugin/plugin.json)for a directory with no manifest. A non-emptySkipped (n)line withSynced (0)is exit 0 but still means nothing landed — read both lines.
- Windows:
- If Melodic scripts are unavailable, still perform real directory copies of each plugin dir (must contain
.cursor-plugin/plugin.json) into~/.cursor/plugins/local/<name>/(Windows:%USERPROFILE%\.cursor\plugins\local\). Do not rely on junctions unless the user explicitly accepts Cursor may reject them (docs mention symlinks for local test; Melodic default is real copies). - Report synced names + destination root.
- Instruct Developer: Reload Window.
- If the plugin still does not appear, check the two gates the live Test plugins locally section documents before assuming the sync failed:
- Local imports must be permitted. On Teams/Enterprise admins control this with Allow Local Plugin Imports under Dashboard → Settings → Security & Identity → Marketplace and Plugins, and it is off by default on Enterprise.
- "If a marketplace plugin with the same name is already installed, that install takes precedence over the local copy" — uninstall the marketplace copy first, or a correct sync will look like a no-op.
Out of scope
- Team Marketplace Dashboard import (use
install-marketplace/update-plugins). - Committing secrets into plugins.