👨‍💻 Creator

📑 Table of Contents

| Section | Description | |:--------|:------------| | Overview | What is xdev-vps-cli | | Features | Core capabilities at a glance | | Installation | Prerequisites & setup | | Quick Start | Deploy in 4 steps | | Commands Reference | All available commands | | Configuration | Global, project & ignore files | | Project Structure | Local file layout | | Deployment Flow | How push & rollback work | | Backup System | Tar-based backup architecture | | VS Code Extension | Push tracker badges | | Requirements | Platform & version support | | License | MIT License |

🔍 Overview

xdev-vps-cli is a production-ready Node.js command-line tool designed for developers who want a streamlined workflow for deploying local projects to aaPanel VPS servers.

It eliminates the complexity of manual SSH and SFTP operations by providing an intuitive, interactive interface with smart deployment capabilities.

Whether you're deploying a PHP application, a Node.js backend, or any static website — xdev handles the heavy lifting with intelligent file change detection, automatic tar backups before every deployment, and instant rollback capabilities when things go wrong.

✨ Features

| Feature | Description | |:--------|:------------| | 🚀 Smart Incremental Deploy | Only uploads files changed since the last push — saves time & bandwidth | | 📦 Tar Backups | Creates compressed .tar archives on the server before every deployment | | ⏪ One-Click Rollback | Restore to the previous version instantly from the tar backup | | 📂 Interactive Directory Browser | Navigate VPS directories with arrow keys — no manual path typing | | 🎨 Beautiful Terminal UI | Spinners, progress bars, color-coded output, and clear status indicators | | 🔗 Multi-Link Support | Link one project to multiple VPS directories (production, staging, etc.) | | 🌐 Cross-Platform | Native support for Windows, macOS, and Linux — no external tools required | | ⚙️ Global Config | Configure VPS once, use across all projects | | 🧩 VS Code Extension | Yellow ⬆ badge on unpushed files — auto-installed with xdev init | | 🧹 Clean & Clear | xdev clear to wipe history, xdev h/xdev s to hide/show config files |

📥 Installation

Prerequisites

| Requirement | Minimum Version | |:------------|:----------------| | Node.js | >= 14.0.0 | | npm | >= 6.0.0 | | SSH | Password authentication enabled on your VPS |

Install Globally

npm install -g xdev-vps-cli

Verify the installation:

xdev --version    # → 14.0.1
xdev --help       # → Show all commands

💡 The VS Code Push Tracker extension is automatically installed if VS Code is detected.

🚀 Quick Start

Get deployed in under 2 minutes — just 4 steps:

Step 1 — Configure VPS

xdev config

VPS Host:       192.168.1.100
SSH User:       root
SSH Password:   ********
SSH Port:       22
aaPanel Root:   /www/wwwroot

Step 2 — Initialize Project

cd my-awesome-project
xdev init

✔ Project initialized
✔ Created .xdev/ directory
✔ Created .xdevignore
✔ XDev Push Tracker extension installed

Step 3 — Link to VPS

xdev link production

? Select directory (/www/wwwroot)
  ↩ Go back
  📁 api.example.com
  📁 myapp.example.com
❯ ✓ Use this folder

Step 4 — Deploy! 🎉

xdev push production

✔ Connection established
✔ Found 5 changed files
✔ Backup created
████████████████████ 100%
✔ Deployment complete

📖 Commands Reference

Command Overview

| Command | Description | Flags | |:--------|:------------|:------| | xdev init | Initialize project | — | | xdev config | Configure VPS connection | --edit | | xdev link <name> | Link project to VPS directory | — | | xdev push [name] | Deploy to VPS | --all --info | | xdev rollback <name> | Restore previous version | — | | xdev list | View/manage project links | --clear [name] --all | | xdev info | View push history | — | | xdev clear | ⚠️ Clear history & VPS backups | — | | xdev h | Hide .xdev/ & .xdevignore | — | | xdev s | Show .xdev/ & .xdevignore | — | | xdev extension | Install VS Code extension | --uninstall | | xdev add:folder | Create a new folder on the VPS | — | | xdev update | Update xdev-vps-cli to latest | — | | xdev uninstall | Uninstall xdev-vps-cli | — |

xdev init

Initialize the current folder as an xdev project.

xdev init

What it creates:

my-project/
├── .xdev/
│   ├── project.json    ← Link mappings
│   ├── pushlog.json    ← Deployment history
│   └── state.json      ← File state tracking
└── .xdevignore         ← Files excluded from deployment

Auto-actions:

• Installs the VS Code Push Tracker extension (if VS Code is detected)
• Creates a default .xdevignore with sensible defaults

# Dependencies
node_modules/

# XDev internal directory
.xdev/

# Environment files (security)
.env
.env.local
.env.*.local

# Build outputs
dist/
build/

# Logs
*.log

# OS generated files
.DS_Store
Thumbs.db

# IDE and editor directories
.vscode/
.idea/

# Temporary and cache files
*.tmp
*.temp
*.cache
*.bak

# Package manager files
.yarn/

# Test coverage
coverage/

# XDev ignore file itself
.xdevignore

xdev config

Configure VPS connection settings. Run this first before any other command.

xdev config           # Interactive setup
xdev config --edit    # View current configuration

| Prompt | Description | Default | |:-------|:------------|:--------| | VPS Host | Server IP or domain | — | | SSH User | SSH username | root | | SSH Password | SSH password | — | | SSH Port | SSH port number | 22 | | aaPanel Root | Web root directory | /www/wwwroot |

Configuration is saved globally at ~/.xdev/config.json — shared across all projects.

View current config:

  Current Configuration

    Host:          192.168.1.100
    SSH User:      root
    SSH Password:  ********
    SSH Port:      22
    aaPanel Root:  /www/wwwroot

    Config file: ~/.xdev/config.json

xdev link

Link your local project to a directory on your VPS.

xdev link <link-name>

Examples:

xdev link production      # Production server
xdev link staging         # Staging server
xdev link client-demo     # Client demo environment

The CLI connects to your VPS and presents an interactive directory browser:

? Select directory (/www/wwwroot)
  ↩ Go back
  📁 api.example.com
  📁 blog.example.com
  📁 myapp.example.com
  📁 static.example.com
❯ ✓ Use this folder

Navigate with ↑↓ arrow keys, Enter to select. The mapping is saved in .xdev/project.json:

{
  "links": {
    "production": "/www/wwwroot/myapp.example.com",
    "staging": "/www/wwwroot/staging.example.com"
  }
}

xdev push

Deploy your project to the linked VPS directory.

Incremental Push (default)

xdev push <link-name>

Only deploys files that have changed since the last push.

| Step | Action | |:-----|:-------| | 1 | Connect to VPS via SSH | | 2 | Scan local files for changes (modified time + size) | | 3 | Create a tar backup on VPS (backup.tar) | | 4 | Upload changed files via SFTP (5 parallel uploads) | | 5 | Update push log & file state |

✔ Connection established
✔ Found 3 changed files
✔ Backup created

Uploading files
████████████████████ 100% | 3/3 files

✔ Deployment complete
  Version: v1710539200.A3B7
  Files: 3
  Backup: production_v1710539200.A3B7_1710539200

Full Push

xdev push <link-name> --all

Deploys all project files — use for initial deployment or full sync.

View Push History

xdev push --info

xdev rollback

Restore your VPS directory to the previous version from the tar backup.

xdev rollback <link-name>

Example:

xdev rollback production

| Step | Action | |:-----|:-------| | 1 | Read last push entry from pushlog.json | | 2 | Locate the backup.tar file on VPS | | 3 | Restore files from the tar archive | | 4 | Clean up the backup directory | | 5 | Remove the push entry from history |

✔ Connection established
✔ Files restored from backup
✔ Backup cleaned up
✔ Rollback complete

⚠️ Rollback restores to the last push only. Each rollback undoes one push.

xdev list

View and manage project links.

xdev list                       # View all links
xdev list --clear <link-name>   # Remove a specific link
xdev list --clear --all         # Remove all links

Output:

  Project Links

    production → /www/wwwroot/example.com
    staging    → /www/wwwroot/staging.example.com

xdev info

Display deployment history for the current project.

xdev info

  Project: my-awesome-project

  Last Push
    Target:        production
    Time:          2024-03-15 14:30
    Version:       v1710539200.A3B7
    Type:          partial
    Files changed: 3

  History

    1. production partial   v1710539200.A3B7
    2. production full      v1710538300.X9C2
    3. staging partial      v1710537500.K4D8

xdev clear

⚠️ DANGER ZONE — Clear all push history and remove VPS backups.

xdev clear

After running this command, rollback will NOT be possible. All server backups will be permanently deleted.

Safety measures: Requires double confirmation — first a yes/no prompt, then typing the project name.

| What gets deleted | Location | |:------------------|:---------| | Push history | Local .xdev/pushlog.json | | File state tracking | Local .xdev/state.json | | All backup .tar files | VPS .xdev/backups/ in all linked directories |

What is preserved: Your project links (.xdev/project.json) remain intact. You can xdev push again immediately.

  ⚠  DANGER ZONE — Clear Project History

  Project: my-awesome-project
  Links:   production, staging
  Pushes:  12 push records

  ⚠  After this, rollback will NOT be possible!
  ⚠  All server backups will be permanently deleted!

? Are you sure? (y/N) y
? Type the project name "my-awesome-project" to confirm: my-awesome-project

✔ Removed .xdev/ from production
✔ Removed .xdev/ from staging
✔ Local push history cleared

✔ Clear complete

xdev h / xdev s

Hide or show the .xdev/ directory and .xdevignore file.

| Command | Action | Scope | |:--------|:-------|:------| | xdev h | Hide config files | VS Code Explorer + Windows File Explorer | | xdev s | Show config files | VS Code Explorer + Windows File Explorer |

How it works:

| Platform | Method | |:---------|:-------| | VS Code | Adds/removes files.exclude in .vscode/settings.json | | Windows | Sets/removes hidden attribute via attrib +h / attrib -h | | macOS/Linux | Files starting with . are already hidden by default |

# xdev h
✔ .xdev/ and .xdevignore are now hidden
  Use `xdev s` to show them again.

# xdev s
✔ .xdev/ and .xdevignore are now visible
  Use `xdev h` to hide them again.

xdev extension

Install or uninstall the XDev Push Tracker VS Code extension.

xdev extension              # Install
xdev extension --uninstall  # Uninstall

| Feature | Description | |:--------|:------------| | ⬆ Yellow badge | Appears on file tabs & explorer for unpushed files | | Status bar | Shows count of unpushed files | | Auto-refresh | Clears badges after xdev push | | No reload needed | Activates immediately on install |

💡 The extension is automatically installed when you run xdev init. This command is for manual install/reinstall.

xdev add:folder

Browse and create a new folder directly on the VPS.

xdev add:folder

Workflow:

1. Connects to your VPS.
2. Interactive directory browser to select the parent folder.
3. Prompts for the new folder name.
4. Confirms and creates the directory on the server.

✔ Connection established
? Browse to the parent directory (/www/wwwroot)
❯ 📁 myapp.example.com
? Enter the name for the new folder: uploads
? Create folder "uploads" inside "/www/wwwroot/myapp.example.com"? Yes
✔ Folder created: /www/wwwroot/myapp.example.com/uploads

xdev update

Update xdev-vps-cli to the latest version from npm.

xdev update

What it does:

1. Connects to the npm registry.
2. Checks for the latest version of xdev-vps-cli.
3. Installs the latest version globally using npm install -g.

✔ Successfully updated xdev-vps-cli to the latest version.

You can verify the version by running: xdev --version

xdev uninstall

Completely uninstall xdev-vps-cli and remove all configuration files.

xdev uninstall

| Step | Action | |:-----|:-------| | 1 | Confirmation prompt | | 2 | Remove VS Code extension | | 3 | Delete global config directory (~/.xdev/) | | 4 | Uninstall npm package globally |

? Are you sure you want to uninstall xdev-vps-cli? (y/N) y

✔ VS Code extension removed
✔ Configuration files removed
✔ Package uninstalled

✔ xdev-vps-cli has been uninstalled successfully.

⚙️ Configuration

Configuration Files Overview

| File | Location | Scope | Description | |:-----|:---------|:------|:------------| | config.json | ~/.xdev/config.json | Global | VPS connection settings | | project.json | .xdev/project.json | Project | Link name → VPS path mappings | | pushlog.json | .xdev/pushlog.json | Project | Deployment history log | | state.json | .xdev/state.json | Project | File modification tracking | | .xdevignore | Project root | Project | Files excluded from deployment |

Global Configuration

// ~/.xdev/config.json
{
  "host": "192.168.1.100",
  "user": "root",
  "password": "your-ssh-password",
  "port": 22,
  "aapanelRoot": "/www/wwwroot"
}

Project Configuration

// .xdev/project.json
{
  "links": {
    "production": "/www/wwwroot/example.com",
    "staging": "/www/wwwroot/staging.example.com"
  }
}

Push Log

// .xdev/pushlog.json
{
  "pushes": [
    {
      "target": "production",
      "timestamp": 1710539200,
      "version": "v1710539200.A3B7",
      "type": "partial",
      "files": ["index.php", "api/users.php", "config/app.php"],
      "backup": "production_v1710539200.A3B7_1710539200"
    }
  ]
}

📁 Project Structure

Local Project (after xdev init)

my-project/
├── .xdev/                      ← xdev configuration (use xdev h to hide)
│   ├── project.json            ← Link name → VPS path mappings
│   ├── pushlog.json            ← Deployment history with versions
│   └── state.json              ← File modification timestamps & sizes
├── .xdevignore                 ← Files excluded from deployment
├── src/
│   ├── index.php
│   └── api/
│       └── users.php
├── public/
│   └── assets/
└── config/
    └── database.php

VPS Server (after xdev push)

/www/wwwroot/example.com/
├── .xdev/                              ← xdev server data
│   └── backups/
│       ├── production_v17105_1710539200/
│       │   └── backup.tar              ← Full snapshot before push #1
│       └── production_v17106_1710540100/
│           └── backup.tar              ← Full snapshot before push #2
├── index.php                           ← Deployed files
├── api/
│   └── users.php
├── public/
│   └── assets/
└── config/
    └── database.php

🔄 Deployment Flow

Incremental Push (xdev push <name>)

 ┌──────────────────────┐
 │    xdev push prod    │
 └──────────┬───────────┘
            │
            ▼
 ┌──────────────────────┐
 │  Connect to VPS      │  SSH connection with saved credentials
 └──────────┬───────────┘
            │
            ▼
 ┌──────────────────────┐
 │  Scan for changes    │  Compare mtime + size vs state.json
 └──────────┬───────────┘
            │
            ▼
 ┌──────────────────────┐
 │  Create tar backup   │  tar cf backup.tar (excludes .xdev/)
 │  on VPS server       │  Stored in .xdev/backups/{name}_{version}/
 └──────────┬───────────┘
            │
            ▼
 ┌──────────────────────┐
 │  SFTP upload files   │  5 parallel uploads with progress bar
 └──────────┬───────────┘
            │
            ▼
 ┌──────────────────────┐
 │  Update state & log  │  pushlog.json + state.json updated
 └──────────────────────┘

Full Push (xdev push <name> --all)

 ┌──────────────────────┐
 │ xdev push prod --all │
 └──────────┬───────────┘
            │
            ▼
 ┌──────────────────────┐
 │  Connect to VPS      │
 └──────────┬───────────┘
            │
            ▼
 ┌──────────────────────┐
 │  Create FULL tar     │  Complete directory snapshot
 │  backup on VPS       │
 └──────────┬───────────┘
            │
            ▼
 ┌──────────────────────┐
 │  Upload ALL project  │  Every file (respecting .xdevignore)
 │  files via SFTP      │
 └──────────┬───────────┘
            │
            ▼
 ┌──────────────────────┐
 │  Update state & log  │
 └──────────────────────┘

Rollback (xdev rollback <name>)

 ┌──────────────────────┐
 │ xdev rollback prod   │
 └──────────┬───────────┘
            │
            ▼
 ┌──────────────────────┐
 │  Connect to VPS      │
 └──────────┬───────────┘
            │
            ▼
 ┌──────────────────────┐
 │  Find last backup    │  Read pushlog.json → locate backup.tar
 └──────────┬───────────┘
            │
            ▼
 ┌──────────────────────┐
 │  Restore from tar    │  tar xf backup.tar → overwrites current
 └──────────┬───────────┘
            │
            ▼
 ┌──────────────────────┐
 │  Cleanup backup dir  │  Remove the used backup folder
 │  Update push log     │  Remove the push entry
 └──────────────────────┘

📦 Backup System

How Backups Work

Every time you run xdev push, a tar archive of the entire deployed directory is created on the VPS before any files are uploaded. This ensures you always have a complete snapshot to roll back to.

Backup Architecture

| Component | Details | |:----------|:--------| | Format | Standard .tar archive (uncompressed for speed) | | Location | {remote_dir}/.xdev/backups/{backup_name}/backup.tar | | Contents | Full directory snapshot (excludes .xdev/ itself) | | Naming | {link-name}_{version}_{unix-timestamp} | | Cleanup | Automatically deleted after successful rollback | | Clear | Use xdev clear to remove all backups from VPS |

Backup Directory Structure on VPS

/www/wwwroot/example.com/
├── .xdev/
│   └── backups/
│       │
│       ├── production_v1710539200.A3B7_1710539200/
│       │   └── backup.tar              ← 📦 Snapshot before push #3
│       │
│       ├── production_v1710538300.X9C2_1710538300/
│       │   └── backup.tar              ← 📦 Snapshot before push #2
│       │
│       └── staging_v1710537500.K4D8_1710537500/
│           └── backup.tar              ← 📦 Snapshot before push #1
│
├── index.php                           ← Current live files
├── api/
│   └── users.php
└── config/
    └── database.php

Backup Lifecycle

  xdev push             xdev push             xdev rollback
  (1st deploy)          (2nd deploy)          (undo 2nd)
       │                     │                     │
       ▼                     ▼                     ▼
 ┌───────────┐         ┌───────────┐         ┌───────────┐
 │ Create    │         │ Create    │         │ Restore   │
 │ backup #1 │         │ backup #2 │         │ backup #2 │
 └───────────┘         └───────────┘         └─────┬─────┘
                                                   │
                                              Delete backup #2
                                              Remove push entry

Important Notes

⚠️ Backups are stored on the VPS — they consume server disk space. Use xdev clear periodically to free space.

⚠️ Rollback is sequential — you can only roll back the most recent push per link. To go further back, rollback multiple times.

⚠️ xdev clear is irreversible — it permanently deletes all backups from the VPS and local history.

🧩 VS Code Extension

The XDev Push Tracker extension is bundled with the CLI and provides visual indicators for files with unpushed changes.

| Indicator | Where | Description | |:----------|:------|:------------| | ⬆ Yellow badge | File tabs + Explorer | Files modified after last xdev push | | Status bar | Bottom-left | ☁ XDev: N unpushed counter | | Auto-refresh | Everywhere | Badges clear after xdev push |

How It Works

1. Extension reads .xdev/state.json (file timestamps from last push)
2. Compares each file's current modification time vs lastPushTime
3. Files modified after the last push → yellow ⬆ badge
4. Watches state.json for changes → auto-refreshes when you push

Installation

| Method | Command | |:-------|:--------| | Automatic | Installed with xdev init | | Manual | xdev extension | | Uninstall | xdev extension --uninstall |

💡 The extension activates on VS Code startup — no reload required.

📋 Requirements

System Requirements

| Requirement | Minimum | Recommended | |:------------|:--------|:------------| | Node.js | >= 14.0.0 | >= 18.0.0 | | npm | >= 6.0.0 | >= 9.0.0 | | VS Code | >= 1.74.0 | Latest | | SSH | Password auth enabled | — |

Platform Support

| Platform | Status | Notes | |:---------|:-------|:------| | 🪟 Windows | ✅ Full support | Native, no additional tools | | 🍎 macOS | ✅ Full support | Native, no additional tools | | 🐧 Linux | ✅ Full support | Native, no additional tools |

Terminal Output Examples

  xdev-vps-cli — Deploy to aaPanel VPS

✔ Connection established
✔ Found 5 changed files
✔ Backup created

Uploading files
████████████████████ 100% | 5/5 files

✔ Deployment complete
  Version: v1710539200.A3B7
  Files: 5
  Backup: production_v1710539200.A3B7_1710539200

  xdev-vps-cli — Deploy to aaPanel VPS

✔ Connection established
✔ No files changed

✔ No files changed. Nothing to deploy.

  xdev-vps-cli — Deploy to aaPanel VPS

✖ Connection failed
✖ Connection refused (ECONNREFUSED)

📄 License

MIT License — Copyright (c) 2024 Nex Ayush

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.