link

Use link to opt a repository into Shepherd coordination by writing a committed .shepherd marker file naming the workspace. Unlike work, done, announce, and sync, link is never gated behind an existing coordination session — it works even when the repo isn't linked yet, since that's exactly the problem it solves. Most agents only need to run it once per repo; after that, work/done/announce/sync just work.

Input

Example

{
  "workspace": "acme-corp"
}

Result

A one-line advisory or confirmation, depending on the situation:

• If linking succeeds, Shepherd returns something like Linked this repo to \acme-corp` — coordinating in `acme-corp` now.`
• On a self-hosted deployment, there's exactly one valid workspace (the hub's configured workspace), so calling link with no workspace argument auto-links to it immediately.
• On Korso-hosted deployments, calling link with no workspace argument lists the workspaces the account belongs to: if there's exactly one, it auto-picks it the same way; if there are several, it lists the slugs and asks the agent to check with its human user, then call link again with the chosen slug; if there are none, it says to create one in the Shepherd dashboard first.

Behavior notes

• You can only link to a workspace you are a member of. Passing an invalid slug is rejected — self-host rejects anything other than its single configured workspace, and hosted rejects any slug the account isn't a member of, listing the valid ones instead.
• Writes a .shepherd marker file at the repo root containing only the workspace slug (e.g. { "workspace": "acme-corp" }) — never a token. Commit it so every teammate who clones the repo auto-joins the same workspace.
• Takes effect immediately in the current session — no restart required.
• Clears any prior decline for this repo; choosing a workspace always overrides a previous "don't ask again."
• If the hub is unreachable while listing hosted workspaces, link reports that and changes nothing rather than erroring.
• Use unlink to opt back out, or decline to stay uncoordinated without linking.