cloudpanel-sdk

Node.js SDK for managing CloudPanel via SSH.
Wraps every clpctl CLI command into a clean, promise-based API — perfect for building hosting panels, automation scripts, or full SaaS hosting platforms.

Installation

npm install cloudpanel-sdk

Quick Start

const { CloudPanel } = require('cloudpanel-sdk');

const cp = new CloudPanel({
  host: '1.2.3.4',        // Your VPS IP
  username: 'root',        // Default: 'root'
  password: 'yourSecret',  // SSH password
});

async function main() {
  // 1. Connect to VPS
  await cp.connect();

  // 2. Verify CloudPanel is installed (throws if not)
  const info = await cp.verify();
  console.log(info);
  // { installed: true, clpctlPath: '/usr/bin/clpctl', version: '2.4.0', ... }

  // 3. Use any module
  await cp.site.addPhp({
    domainName: 'mysite.com',
    phpVersion: '8.4',
    vhostTemplate: 'WordPress',
    siteUser: 'myuser',
    siteUserPassword: 'SecureP@ss!',
  });

  // 4. Install SSL
  await cp.letsEncrypt.installCertificate({ domainName: 'mysite.com' });

  // 5. Done — disconnect
  cp.disconnect();
}

main().catch(console.error);

Config Options

| Option | Type | Default | Description | |--------------|----------|-------------|------------------------------------------| | host | string | (required)| VPS IP address or hostname | | username | string | 'root' | SSH username | | password | string | — | SSH password (use this OR privateKey) | | privateKey | string | — | Path to local private key file | | port | number | 22 | SSH port | | timeout | number | 15000 | Connection timeout in ms |

CloudPanel Detection

// Non-throwing check — returns result object
const result = await cp.check();
console.log(result);
// {
//   installed: true,
//   clpctlPath: '/usr/bin/clpctl',
//   version: '2.4.0',
//   serviceStatus: 'active',
//   hasDatabase: true,
//   details: 'CloudPanel detected at /usr/bin/clpctl. Service: active.'
// }

// Throwing check — throws if CloudPanel is not installed
await cp.verify();

API Reference

All methods return a Promise<object> with this shape:

{
  command: 'clpctl site:add:php',  // command that was run
  success: true,                   // true if exit code === 0
  stdout: '...',                   // raw stdout
  stderr: '...',                   // raw stderr
  code: 0                          // exit code
}

🌐 cp.site

| Method | Description | |--------|-------------| | site.addPhp(opts) | Add a PHP site | | site.addNodejs(opts) | Add a Node.js site | | site.addStatic(opts) | Add a Static HTML site | | site.addPython(opts) | Add a Python site | | site.addReverseProxy(opts) | Add a Reverse Proxy site | | site.installCertificate(opts) | Install a custom SSL certificate | | site.delete(opts) | Delete a site |

site.addPhp(opts)

await cp.site.addPhp({
  domainName: 'mysite.com',          // required
  phpVersion: '8.4',                 // default: '8.4'
  vhostTemplate: 'WordPress',        // default: 'Generic'
  siteUser: 'myuser',                // required
  siteUserPassword: 'SecureP@ss!',   // required
});

site.addNodejs(opts)

await cp.site.addNodejs({
  domainName: 'myapp.com',
  nodejsVersion: 22,      // default: 22
  appPort: 3000,          // default: 3000
  siteUser: 'myuser',
  siteUserPassword: 'SecureP@ss!',
});

site.addStatic(opts)

await cp.site.addStatic({
  domainName: 'mysite.com',
  siteUser: 'myuser',
  siteUserPassword: 'SecureP@ss!',
});

site.addPython(opts)

await cp.site.addPython({
  domainName: 'myapp.com',
  pythonVersion: '3.9',   // default: '3.9'
  appPort: 8080,          // default: 8080
  siteUser: 'myuser',
  siteUserPassword: 'SecureP@ss!',
});

site.addReverseProxy(opts)

await cp.site.addReverseProxy({
  domainName: 'mysite.com',
  reverseProxyUrl: 'http://127.0.0.1:8000',
  siteUser: 'myuser',
  siteUserPassword: 'SecureP@ss!',
});

site.installCertificate(opts)

await cp.site.installCertificate({
  domainName: 'mysite.com',
  privateKey: '/path/to/private.key',
  certificate: '/path/to/certificate.crt',
  certificateChain: '/path/to/chain.crt',  // optional
});

site.delete(opts)

await cp.site.delete({
  domainName: 'mysite.com',
  force: true,  // default: false — auto-confirms deletion
});

🗄️ cp.database

| Method | Description | |--------|-------------| | database.showMasterCredentials() | Show DB host/user/pass/port (root only) | | database.add(opts) | Add a new database to a site (root only) | | database.exportDB(opts) | Export a database as dump | | database.importDB(opts) | Import a database from dump | | database.backup(opts) | Backup all/specific databases (root only) |

// Show credentials
await cp.database.showMasterCredentials();

// Add DB
await cp.database.add({
  domainName: 'mysite.com',
  databaseName: 'my_db',
  databaseUserName: 'my_user',
  databaseUserPassword: 'dbPass!',
});

// Export (gzipped)
await cp.database.exportDB({ databaseName: 'my_db', file: '/tmp/dump.sql.gz' });

// Import
await cp.database.importDB({ databaseName: 'my_db', file: '/tmp/dump.sql.gz' });

// Backup all
await cp.database.backup({ databases: 'all', retentionPeriod: 7 });

// Backup specific, ignore some
await cp.database.backup({
  databases: 'db1,db2',
  ignoreDatabases: 'information_schema,performance_schema',
});

🔒 cp.letsEncrypt

// Single domain (auto-covers www + non-www)
await cp.letsEncrypt.installCertificate({ domainName: 'mysite.com' });

// With SAN (multiple domains)
await cp.letsEncrypt.installCertificate({
  domainName: 'mysite.com',
  subjectAlternativeName: 'api.mysite.com,admin.mysite.com',
});

👤 cp.user

| Method | Description | |--------|-------------| | user.add(opts) | Add a CloudPanel user | | user.delete(opts) | Delete a user | | user.list() | List all users | | user.resetPassword(opts) | Reset user password | | user.disableMfa(opts) | Disable 2FA for a user |

// Add admin
await cp.user.add({
  userName: 'john.doe',
  email: '[email protected]',
  firstName: 'John',
  lastName: 'Doe',
  password: 'Secure!123',
  role: 'admin',  // 'admin' | 'site-manager' | 'user'
  timezone: 'Asia/Jakarta',
  status: 1,
});

// Add site-restricted user
await cp.user.add({
  userName: 'client1',
  email: '[email protected]',
  firstName: 'Client',
  lastName: 'One',
  password: 'Secure!123',
  role: 'user',
  sites: 'domain.com,shop.domain.com',
});

await cp.user.list();
await cp.user.resetPassword({ userName: 'john.doe', password: 'NewPass!456' });
await cp.user.disableMfa({ userName: 'john.doe' });
await cp.user.delete({ userName: 'john.doe' });

📋 cp.vhostTemplate

await cp.vhostTemplate.list();
await cp.vhostTemplate.import();
await cp.vhostTemplate.add({ name: 'My App', file: '/tmp/template.tpl' });
await cp.vhostTemplate.view({ name: 'WordPress' });
await cp.vhostTemplate.delete({ name: 'My App' });

🔐 cp.auth

await cp.auth.enableBasicAuth({ userName: 'admin', password: 'secret' });
await cp.auth.disableBasicAuth();

☁️ cp.cloudflare

await cp.cloudflare.updateIPs();

⚙️ cp.system

// Reset file/dir permissions
await cp.system.resetPermissions({
  directories: 770,
  files: 660,
  path: '/home/myuser/htdocs/mysite.com',
});

// Purge all Varnish cache
await cp.system.purgeVarnishCache({ purge: 'all' });

// Purge specific tags
await cp.system.purgeVarnishCache({ purge: 'tag1,tag2' });

// Purge single URL
await cp.system.purgeVarnishCache({ purge: 'https://mysite.com/page.html' });

🔧 Raw Exec (escape hatch)

// Run any command directly on the VPS
const result = await cp.exec('nginx -t');
console.log(result.stdout);

Error Handling

const cp = new CloudPanel({ host: '1.2.3.4', password: 'secret' });

try {
  await cp.connect();
  await cp.verify(); // throws if CloudPanel not installed

  const result = await cp.site.addPhp({ ... });

  if (!result.success) {
    console.error('Command failed:', result.stderr);
  }
} catch (err) {
  console.error(err.message);
} finally {
  cp.disconnect();
}

Private Key Authentication

const cp = new CloudPanel({
  host: '1.2.3.4',
  username: 'root',
  privateKey: '/home/youruser/.ssh/id_rsa', // local path to your key
});

License

MIT