Files
skillshare/website/docs/reference/commands/pull.md
T
Willie ed2f1c0675 docs: explain what cross-machine sync carries for plugins, MCP and hooks
Users syncing Codex setups between macOS and Windows with push/pull
found that plugins did not follow, imports would not reinstall on the
second machine, and installed plugins never updated. The pages implied
pull syncs everything, but plugins, hooks and MCP live in config.yaml,
which no git_root scope tracks, and pull never runs sync --all or plugin
sync.

Document what each scope carries, the extra sync steps after pull, how
to version MCP through sources.mcp in a root-scope repo, why plugins
must be re-added from an HTTPS source, and what stays per machine. Add
troubleshooting for a CLI missing from PATH and a missing native
marketplace, and pin heading anchors so translated pages link correctly.
2026-10-02 22:22:15 +08:00

4.9 KiB

sidebar_position
sidebar_position
2

pull

Pull from git remote and sync to all targets.

skillshare pull              # Pull and sync
skillshare pull --dry-run    # Preview
skillshare pull --force      # Replace local with remote on first pull

When to Use

  • Sync skills from another machine that pushed changes
  • Get the latest skills after someone else pushed updates
  • Start working on a new machine after init --remote

What Happens

flowchart TD
    CMD["skillshare pull"]
    CHECK["1. Check repository status"]
    PULL["2. Pull from remote"]
    SYNC["3. Sync to all targets"]
    CMD --> CHECK --> PULL --> SYNC

Options

Flag Description
--dry-run, -n Preview without making changes
--force, -f On first pull conflict, replace local skills with remote

Git Root Scope

pull operates on the directory selected by the git_root config field (default: skills source). See commit — Git Root Scope for the scope table. If git_root was changed but the git repo still lives in another scope's directory, pull prints a "Git root mismatch" error with the exact git init / mv commands to fix it. See Changing the scope after init.

After pulling, pull syncs what the scope holds: skills runs sync, agents runs sync agents, root runs both, and extras runs sync extras.

Plugins, MCP servers and hooks are settings in config.yaml, which no scope tracks, so pull neither brings nor applies them. See Cross-Machine Sync — Plugins, MCP and Hooks.

Prerequisites

Your source directory must be a git repository with a remote:

# Check if ready:
skillshare status
# Shows: Git: initialized with remote

Local Changes Warning

If you have uncommitted changes, pull will fail:

$ skillshare pull
Local changes detected
  Run: skillshare push
  Or:  cd ~/.config/skillshare/skills && git stash

Solutions:

# Option 1: Commit locally first, without pushing
skillshare commit -m "Local changes"
skillshare pull

# Option 2: Push your changes first
skillshare push
skillshare pull

# Option 3: Stash your changes
cd ~/.config/skillshare/skills
git stash
skillshare pull
git stash pop

When Both Machines Committed

If this machine has commits the remote lacks and the remote has commits this machine lacks, pull merges the two histories into a merge commit, then syncs. Push afterwards to share the merge.

Both machines rewrite .metadata.json whenever they install or update a skill, so it often conflicts. pull resolves those conflicts on its own: each skill's entry is merged separately, and when both machines changed the same entry, the one with the later installed_at wins.

A conflict in any other file stops the pull, undoes the merge, and names the files:

$ skillshare pull
git pull failed
pull stopped: this machine and the remote both changed my-skill/SKILL.md; the merge was undone, resolve it with git in ~/.config/skillshare/skills

The repository is left as it was before the pull. To resolve the conflict yourself:

cd ~/.config/skillshare/skills
git pull --no-rebase             # redo the merge and keep the conflicts
# edit the conflicted files, then
git add . && git commit --no-edit
skillshare push
skillshare sync

First Pull with Existing Skills

On first pull (no upstream yet), if both local and remote already contain skill directories, pull attempts a merge to combine both sides. If the merge succeeds, both local and remote skills are preserved.

If there are merge conflicts, pull fails with a non-zero exit code:

$ skillshare pull
Pull failed
  Resolve manually: cd ~/.config/skillshare/skills && git merge --allow-unrelated-histories <remote branch>
  Or force-pull: skillshare pull --force  (replaces local with remote)

Resolve options:

# Resolve conflicts manually, then push
cd ~/.config/skillshare/skills
git add . && git commit
skillshare push

# Or discard local and take remote
skillshare pull --force

Examples

# Standard pull (most common)
skillshare pull

# Preview what would happen
skillshare pull --dry-run

# Replace local with remote on first-pull conflict
skillshare pull --force

Workflow

Typical workflow on a secondary machine:

# Start of day: get latest skills
skillshare pull

# ... work with AI tools ...

# End of day: share any new skills
skillshare collect claude    # If you created new skills
skillshare push -m "Add new skill"

See Also