@akoenig/vex

CLI tool for managing files from network shares to local repositories via symlinks.

Why?

Sometimes you want to have files that are synced, but not part of a git repository.

Installation

npm install -g @akoenig/vex

Usage

Basic Commands

Bind Project to Vault

vex bind <vault-path> [(-p, --project-path directory)]

Unbind Project from Vault

vex unbind [(-p, --path directory)]

List Configurations

vex list

Project Status

vex status [project-path]

Sync Project with Vault

vex sync [project-path]

Add File or Directory to Vault

vex add <path> [project-path]

Remove File from Vault

vex rm <path> [(-p, --project-path directory)] [(-f, --force)]

Commands Explained

Status Command Output

The vex status command shows all files in the vault and their link status in your project:

vex status

Output example:

Project status for: /home/user/projects/my-app

✅ Project is linked
   Vault: /mnt/shared/team-configs
   Linked at: 2024-01-15T10:30:00.000Z

📁 Files and directories in vault (3):
   ✅ CLAUDE.md (file properly linked)
   ✅ templates/ (directory properly linked)
   📄 .claude/config.json (file exists but not symlinked)
   ⭕ new-prompt.md (not linked)

⚠️  Some files have issues. Run 'vex sync' to fix them.

Status Icons:

• ✅ Properly linked: File/directory exists in vault and is correctly symlinked in project
• 📄 File exists but not symlinked: File exists in project but is not a symlink to vault
• ⭕ Not linked: File exists in vault but has no corresponding file in project
• 🔗 Symlink points to wrong location: Symlink exists but points to incorrect location
• ❌ Missing from vault: File is expected but doesn't exist in vault

Sync Command

The vex sync command ensures your local project state matches the vault state by:

What it does:

• Adds new files: Creates symlinks for files that exist in vault but not in project
• Removes orphaned links: Removes symlinks for files that no longer exist in vault
• Fixes broken links: Recreates symlinks that exist but point to wrong locations
• Preserves working links: Leaves correctly functioning symlinks unchanged

When to use sync:

• After team members add new files to the shared vault
• When files are deleted from the shared vault
• To fix broken or missing symlinks in your project
• As part of your regular workflow to stay in sync with the team

Example output:

vex sync

✅ Project synced successfully
   Vault: /mnt/shared/team-configs

✅ Added items (2):
   🔗 new-feature-prompt.md
   🔗 configs/ (directory)

🗑️  Removed items (1):
   ➖ deprecated-prompt.md (no longer in vault)

✅ Unchanged items (3):
   🔗 CLAUDE.md
   🔗 .claude/
   🔗 templates/

📊 Total linked items: 5

Safety features:

• Non-destructive: Only modifies symlinks, never touches actual vault files
• Atomic operations: Either all changes succeed or none are applied
• Detailed reporting: Shows exactly what changed and why

Unbind Command

The vex unbind command completely removes a project from its vault:

What it does:

• Removes all symlinks from the project directory
• Removes the project binding from the configuration
• Preserves all files in the vault (no vault files are deleted)

Example output:

vex unbind

✅ Project unbound successfully
   Project path: /home/user/projects/my-app
   Previous vault: /mnt/shared/team-configs
   Originally linked at: 2024-01-15T10:30:00.000Z

🗑️  Removed symlinks (3):
   📄 CLAUDE.md (file)
   📄 templates/ (directory)
   📄 .claude/ (directory)

⚠️  Note: Files in the vault (/mnt/shared/team-configs) were not touched
   Use 'vex bind <vault-path>' to bind this project again

Directory Linking

Vex links entire directories as single units, not individual files within directories. This approach:

• Simplifies management: One symlink per top-level item in the vault
• Maintains structure: Directory hierarchies are preserved through symlinks
• Improves performance: Fewer filesystem operations and symlinks to manage
• Enables atomic updates: Directory contents can be updated without breaking links

Example:

Vault structure:
/vault/
├── README.md          (file)
├── templates/         (directory)
│   ├── prompt1.md
│   └── prompt2.md
└── configs/           (directory)
    ├── app.json
    └── subdir/
        └── nested.yml

Project structure after linking:
/project/
├── README.md -> /vault/README.md           (file symlink)
├── templates/ -> /vault/templates/         (directory symlink)
└── configs/ -> /vault/configs/             (directory symlink)

Usage Scenarios

Team Configuration Sharing

Context: Share Claude configurations across team members via network drive.

cd ~/projects/my-project
vex bind /mnt/shared/team-configs
vex status  # See what's linked

Multiple Project Types

Context: Different projects need different configurations.

cd ~/projects/frontend-app
vex bind /nas/configs/frontend

cd ~/projects/backend-api  
vex bind /nas/configs/backend

vex list  # View all bindings

Adding and Removing Files

Context: Contribute files to the shared vault or clean up obsolete files.

# Add new files to vault
echo "New prompt" > new-feature.md
vex add new-feature.md

# Remove obsolete files (with safety prompt)
vex rm old-prompt.md --force

Configuration

Configurations are stored in ~/.vex/:

• configs.json - Configuration definitions
• projects.json - Project bindings

File Discovery

Vex automatically discovers and links all top-level files and directories in the vault:

• Links files and directories at the vault root level
• Excludes system files (.DS_Store, Thumbs.db, etc.)
• Maintains original directory structure through symlinks
• Handles empty directories correctly

Development

See the main repository README for development instructions.