CLI Commands

Complete reference for all vsync commands with examples and options.

Command Overview


vsync <command> [options]

Available commands:

Command	Description
`init`	Initialize configuration
`sync`	Synchronize configurations
`plan`	Preview sync plan without executing
`status`	Check sync status
`list`	List configurations
`clean`	Remove items from targets
`import`	Import from another project

Global options:

--help, -h - Show help
--version, -v - Show version

init

Initialize vsync configuration for project or user level.

Usage


vsync init [options]

Options

--user - Create user-level config (~/.vsync.json)

Interactive Prompts

Tool Detection: Automatically detects existing tool directories
Tool Selection: Choose which tools to manage
Source Selection: Pick your source of truth
Sync Items: Select what to sync (Skills, MCP, Agents, Commands)

Example


$ vsync init
 
🚀 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

What Gets Created

.vsync.json - Configuration file
.vsync-cache/ - Cache directory
.vsync-cache/manifest.json - Sync tracking manifest

sync

Synchronize configurations from source to target tools.

Usage


vsync sync [options]

Options

--dry-run - Preview changes without applying them
--prune - Enable prune mode (delete items not in source)
--user - Sync user-level configs
-y, --yes - Skip confirmation prompt

Sync Modes

Safe Mode (Default)

Only creates and updates—never deletes.


vsync sync

Output Example:


📖 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)

? Proceed with sync? (Y/n) y

✓ Sync completed in 1.2s

Prune Mode

Strict mirroring—deletes items not in source.


vsync sync --prune

Warning: Items in targets but not in source will be deleted!

Examples


# Preview changes
vsync sync --dry-run
 
# Sync with strict mirroring
vsync sync --prune
 
# Sync user-level configs
vsync sync --user
 
# Skip confirmation (useful for automation)
vsync sync -y

First-Time Symlink Prompt

On the first sync, vsync will ask about symlink usage for Skills:


? How would you like to sync Skills?
  ❯ Use symlinks (recommended - instant updates, saves space)
    Copy files (traditional - independent copies)

This preference is saved in config and won’t be asked again.

plan

Preview the sync plan without executing any changes.

Usage


vsync plan [options]

Options

--user - Show plan for user-level configs

Example


$ vsync plan
 
📖 Reading source (claude-code)...
  ✓ Found 3 skills
  ✓ Found 2 MCP servers
 
📊 Analyzing differences...
 
📋 Sync Plan (Safe Mode)
 
cursor:
  CREATE:
    • skill/deploy-prod
      Reason: New in source
      Hash: sha256:abc123...
 
  UPDATE:
    • skill/git-release
      Reason: Source hash changed
      Old: sha256:old111...
      New: sha256:new222...
 
  SKIP:
    • skill/api-conventions
      Reason: Hash unchanged
 
Run `vsync sync` to apply this plan

status

Check the current sync status and configuration.

Usage


vsync status [options]

Options

--user - Check user-level status

Example


$ vsync status
 
Configuration Status (Project)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
Source Tool:       claude-code
Target Tools:      cursor, opencode
Last Sync:         2026-01-24 10:30:00 (2 hours ago)
Configuration:     .vsync.json
Manifest:          .vsync-cache/manifest.json
 
Synced Items:
  Skills:          3 items
  MCP Servers:     2 items
 
Tool Status:
  ✓ claude-code    (source)
  ✓ cursor         (synced, up-to-date)
  ✓ opencode       (synced, up-to-date)
 
Health:
  ✓ All targets up-to-date
  ✓ No pending changes
 
Run `vsync plan` to see sync plan

list

List all synced configurations from the source tool.

Usage


vsync list [type] [options]

Arguments

type - Configuration type: skills, mcp, agents, or commands (optional)

Options

--user - List user-level configs

Examples


# List all configs
vsync list
 
# List only skills
vsync list skills
 
# List user-level MCP servers
vsync list mcp --user

Output Example


$ vsync list skills
 
Skills (3 items) - Source: claude-code
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
┌──────────────────┬────────────────────────────────┬──────────────┬────────────┐
│ Name             │ Description                    │ Synced To    │ Hash       │
├──────────────────┼────────────────────────────────┼──────────────┼────────────┤
│ git-release      │ Create releases and changelogs │ cursor, open…│ abc123...  │
│ api-conventions  │ API design patterns            │ cursor, open…│ def456...  │
│ deploy-prod      │ Deploy to production           │ cursor, open…│ ghi789...  │
└──────────────────┴────────────────────────────────┴──────────────┴────────────┘

clean

Remove configurations from target tools (and optionally from source).

Usage


vsync clean [item] [options]

Arguments

item - Item to remove in format type/name (e.g., skill/old-skill)

Options

--user - Clean user-level configs
--from-source - Also delete from source tool (dangerous!)
-y, --yes - Skip confirmation (not applicable with --from-source)

Modes

Remove from Targets Only (Safe)

Default behavior—source unchanged.


vsync clean skill/old-skill

Output:


⚠️  This will remove from target tools only (source unchanged)

Will remove from:
  • cursor (.cursor/skills/old-skill/)
  • opencode (.opencode/skills/old-skill/)

Source (claude-code) will NOT be affected.

? Confirm removal from targets? (y/N) y

✓ Cleanup completed

Delete from Source and All Targets (Dangerous!)

Warning: This is destructive and cannot be undone!


vsync clean skill/old-skill --from-source

Output:


⚠️⚠️⚠️  DANGER ZONE  ⚠️⚠️⚠️

This will delete from the SOURCE tool (claude-code) AND all targets.
This action CANNOT be undone.

Will delete from:
  • claude-code (.claude/skills/old-skill/) ← SOURCE
  • cursor (.cursor/skills/old-skill/)
  • opencode (.opencode/skills/old-skill/)

? Type the name to confirm: old-skill
? Are you absolutely sure? (yes/no) yes

🗑️  Deletion completed

Interactive Mode

Run without arguments for interactive selection:


$ vsync clean
 
? What type do you want to clean?
  ❯ Skills
    MCP Servers
 
? Select items to remove from targets:
  ◯ git-release
  ◯ api-conventions
  ◉ old-skill
 
Selected items (1):
  • skill/old-skill
 
⚠️  This will remove from target tools only (source unchanged)
 
? Confirm removal from targets? (y/N) y

import

Import configurations from another project.

Usage


vsync import <path> [options]

Arguments

path - Path to project directory to import from

Options

--user - Import to user-level

Example


$ vsync import ../other-project
 
Scanning ../other-project...
 
? This directory uses:
  ❯ Claude Code (.claude/ found)
    Cursor (.cursor/ found)
 
? Import from which tool?
  ❯ Claude Code
 
Reading claude-code configuration...
  ✓ Found 5 skills
  ✓ Found 3 MCP servers
 
? What do you want to import? (default: all selected)
  ◉ Skills (5 items)
    • git-release
    • api-conventions
    • deploy-prod
    • test-generator
    • code-reviewer
 
  ◉ MCP Servers (3 items)
    • sqlite
    • github
    • postgres
 
? How to handle conflicts?
  ❯ Skip (keep existing)
    Overwrite (replace existing)
    Rename (add suffix)
 
Processing:
  ✓ Skills: 5 imported (0 skipped)
  ✓ MCP: 3 imported (1 skipped: sqlite already exists)
 
✓ Import completed
 
? Sync to target tools now? (Y/n) y

Common Workflows

Daily Sync After Updates


# 1. Edit configs in source tool
vim ~/.claude/skills/my-skill/SKILL.md
 
# 2. Sync to targets
vsync sync

Preview Before Applying


# 1. Check what would change
vsync plan
 
# 2. If satisfied, apply
vsync sync

Clean Up Old Configs


# Safe cleanup (targets only)
vsync clean skill/old-skill
 
# Strict mirror mode
vsync sync --prune

Import from Another Project


vsync import ../other-project

Automation with —yes


# In CI/CD pipelines
vsync sync --yes

Exit Codes

0 - Success
1 - Error occurred

Getting Help


# General help
vsync --help
 
# Command-specific help
vsync sync --help

Next Steps

Learn about Advanced Features
Check the FAQ for troubleshooting
Explore Configuration options