Getting Started

Get up and running with vsync in just a few minutes.

Installation

vsync can be used without installation via npx, or installed globally for convenience.

Option 1: Run with npx (Recommended)

No installation needed—just run:


npx @nicepkg/vsync

Option 2: Global Installation


npm install -g @nicepkg/vsync

Verify the installation:


vsync --version

Quick Start

1. Initialize Configuration

Navigate to your project directory and run:


vsync init

For global user-level configuration:


vsync init --user

💡 Tip: Learn more about project vs user levels in Core Concepts.

Interactive Setup

The CLI will guide you through the setup process:


🚀 Welcome to vsync!

✔ Detecting existing tools...
✔ Detected: claude-code, cursor

? Which AI coding tools do you use?
  ◉ claude-code (detected)
  ◉ cursor (detected)
  ◯ opencode
  ◯ codex

? Which tool is your source of truth?
  ❯ claude-code

? What do you want to sync?
  ◉ Skills
  ◉ MCP

✔ Configuration created
✔ Cache directory created
✔ Manifest initialized

✅ Setup complete! Run vsync sync to start syncing

📚 Learn more: See Configuration for detailed config options.

2. Sync Your Configs

Once initialized, sync your configurations:


# Safe mode (default: no deletions)
vsync sync
 
# Preview changes without applying
vsync sync --dry-run
 
# Strict mirroring (deletes extra items in targets)
vsync sync --prune

🔍 Details: Understand sync modes in Core Concepts.

Understanding the Output

When you run vsync sync, you’ll see a detailed plan:


📖 Reading source (claude-code)...
  ✓ Found 3 skills
  ✓ Found 2 MCP servers

📊 Analyzing differences...

📋 Sync Plan (Safe Mode)

cursor:
  CREATE:
    • skill/deploy-prod
  UPDATE:
    • skill/git-release
    • mcp/github
  SKIP:
    • skill/api-conventions (unchanged)
    • mcp/sqlite (unchanged)

? Proceed with sync? (Y/n) y

✓ Sync completed in 1.2s

Next Steps

Now that you’ve installed and initialized vsync:

Learn the Concepts: Understand Core Concepts like sync modes and layers
Configure Tools: Explore Configuration options for each tool
Master Commands: Check out all CLI Commands
Quick Reference: Use the Quick Reference cheat sheet
Advanced Usage: Dive into Advanced Features like symlinks

Real-World Examples

Team Onboarding

New team member joins with Claude Code already set up:


cd my-project
vsync init  # Choose Claude Code as source, Cursor & OpenCode as targets
vsync sync  # All tools configured instantly!

User-Level Config Sync

Set up global personal configs once, use everywhere:


vsync init --user  # Configure which tools to sync
vsync sync --user  # Sync personal Skills, MCP servers globally

💡 Related: Learn about configuration layers.

Migration Between Tools

Moving from Cursor to Claude Code:


vsync init  # Choose Cursor as SOURCE (reference standard)
                # Choose Claude Code as TARGET (will pull from source)
vsync sync  # All configs migrated instantly!

📖 More info: See FAQ - Migration Questions.

Troubleshooting

Config File Not Found

If you see “Config file not found”, run vsync init first to create the configuration.

Tool Not Detected

Make sure the tool’s configuration directory exists (e.g., .claude/, .cursor/) in your project or home directory.

Permission Errors

On macOS/Linux, you may need to grant permissions for file operations. Check that you have write access to the target directories.

🔧 More help: See the FAQ for detailed troubleshooting.

Getting Help

Run vsync --help for command overview
Run vsync <command> --help for specific command help
Check the FAQ for common questions
Use the Quick Reference for command examples
Open an issue on GitHub