`quay link`

Manage mirror dirs declared under [install].mirrors in the active profile.

Usage

quay link [OPTIONS] [SUBCOMMAND]

Subcommands:

Subcommand	What
`check`	Verify mirrors are intact; exit non-zero if drifted.
`add <PATH>`	Add a mirror to the project config and populate it for every installed skill.
`remove <PATH>`	Remove a mirror from the project config (does not delete files).

With no subcommand, quay link applies the configured mirrors for the project (idempotent).

Examples

quay link                              # apply mirrors
quay link check                        # CI: fail if mirrors drifted
quay link add .cursor/rules            # add a Cursor mirror
quay link add .claude/skills --strategy auto
quay link remove .cursor/rules         # forget the mirror (files stay)

Flags

Flag	Effect
`--strategy <NAME>` (on `add`)	Mirror strategy. Default `auto` (let quay pick per skill format).
`--force`	Overwrite existing entries even if they conflict with quay's layout.
`--profile`, `--user-config`, `--project`, `--json`	Standard globals.

Mirrors (.claude/, .codex/, .cursor/) mirror the canonical .agents/skills/. Symlink/junction mirrors are transparent, but a copy mirror (Windows, or strategy = "copy") is a real directory — and hand-editing it used to be lost silently on the next apply. quay link now detects and protects those edits:

quay link check reports a copy mirror whose content differs from canonical (mirror content differs from canonical) and exits non-zero. It is read-only — it never creates or overwrites anything.
quay link refuses to overwrite a diverged mirror. Copy your edit into the canonical skill and re-run, or quay link --force to discard the mirror edit.
Discovery is disk-driven: quay link scans all known tool dirs (.agents/.claude/.codex/.cursor), so a mirror someone added outside the config is still seen. If no .agents canonical exists, a lone tool dir is treated as the source of truth and left untouched.

Adopting an unmanaged dir (`install.auto_link`)

When quay link finds an unmanaged tool dir whose content is byte-identical to canonical, it can adopt it — convert it to a managed mirror (a symlink on most platforms) and register it as a mirror. This is opt-in: the first interactive run asks, and records your choice as install.auto_link in .quay/config.toml (true = adopt, false = report only). Non-interactive runs (--json, CI) never adopt or write config; they report the dir and exit non-zero so the decision surfaces.

When to use this vs …

quay add — already applies your current mirrors. link is for changing the mirror set or auditing it.
quay scan — does not check mirror drift; it checks skill drift. Pair scan + link check for a full audit.

Caveats

link remove deletes the config entry, not the directory on disk. To also clean files, rm -rf afterwards.
link check is the canonical CI gate. Exit code 0 = clean; non-zero = at least one mirror is missing or out-of-sync.
link check is read-only — it detects drift but never creates or overwrites mirrors.
Without --force, quay link refuses to overwrite a mirror whose content diverged from canonical (your edit is preserved). --force overwrites diverged mirror dirs without backup — use carefully.

`--help`

Apply or verify mirrors, reconciling canonical against known tool dirs on disk

Usage: quay link [OPTIONS] [COMMAND]

Commands:
  check   Verify mirrors are intact; exit non-zero if drifted
  add     Add a new mirror to the project config and apply it for every installed skill
  remove  Remove a mirror from the project config (does not delete the mirror dir)
  help    Print this message or the help of the given subcommand(s)