Guide clpctl Errors in CloudPanel: Command Not Found, Wrong User and Quoting Fixes

Guide clpctl Errors in CloudPanel: Command Not Found, Wrong User and Quoting Fixes - Printable Version

+- AdminsForum (https://adminsforum.com)
+-- Forum: Free & open-source control panels (https://adminsforum.com/Forum-free-open-source-control-panels)
+--- Forum: CloudPanel (https://adminsforum.com/Forum-cloudpanel)
+---- Forum: CloudPanel Guides & Tutorials (https://adminsforum.com/Forum-cloudpanel-guides-tutorials)
+----- Forum: CloudPanel CLI (clpctl) & Automation Guides (https://adminsforum.com/Forum-cloudpanel-cli-clpctl-automation-guides)
+----- Thread: Guide clpctl Errors in CloudPanel: Command Not Found, Wrong User and Quoting Fixes (/Thread-guide-clpctl-errors-in-cloudpanel-command-not-found-wrong-user-and-quoting-fixes)

clpctl Errors in CloudPanel: Command Not Found, Wrong User and Quoting Fixes - JAY - 10-23-2026

clpctl errors in CloudPanel: command not found, wrong user and quoting fixes

clpctl is CloudPanel's command-line tool. It's great for scripting and for emergencies (like resetting a lost password), but its error messages can be confusing. Most problems come from three things: running it as the wrong user, shell quoting, and typos in option names. New to clpctl? Start with getting started with the clpctl command and the clpctl cheat sheet.

The most important rule: root commands vs site user commands
CloudPanel splits clpctl commands into two groups:

Root user commands manage the whole server: adding sites (
Code:
site:add:php
and friends), users (
Code:
user:add
,
Code:
user:reset:password
,
Code:
user:disable:mfa
), databases (
Code:
db:add
,
Code:
db:show:master-credentials
), certificates (
Code:
lets-encrypt:install:certificate
), vhost templates and Basic Auth for the panel.
Site user commands work on one site:
Code:
system:permissions:reset
,
Code:
db:export
,
Code:
db:import
and
Code:
varnish-cache:purge
. (
Code:
db:export
and
Code:
db:import
also exist as root commands.)

So: log in as root for panel-wide jobs, and as the site user (or

Code:

su - siteuser

from root) for site jobs. Running a command as the wrong user is the most common reason clpctl "doesn't work".

Error: "clpctl: command not found"

Check you're on the CloudPanel server and not on your own computer or another VPS:
Code:
hostname
.
Check the tool exists:
Code:
which clpctl
. If it prints nothing as root, CloudPanel isn't installed correctly on this server.
If you switched user with plain
Code:
su siteuser
, use
Code:
su - siteuser
(with the dash) so you get that user's full login environment.

Error: permission denied, or the command refuses to run
You're the wrong user for that command. Use the list above. For site user commands, also

Code:

cd

into the site folder first when the command works on the current path, for example:

Code:

su - siteuser
cd ~/htdocs/example.com
clpctl system:permissions:reset --directories=770 --files=660 --path=.

Passwords with special characters break the command
Characters like

Code:

!

Code:

$

Code:

&

Code:

;

and spaces mean something to the shell. Always put values in single quotes, as CloudPanel's own examples do:

Code:

clpctl user:reset:password --userName='john.doe' --password='My!Strong$Pass'

Inside single quotes, nothing is changed by the shell. Double quotes are not safe for

Code:

$

Code:

!

. If the password itself contains a single quote, pick a different password; it's not worth the trouble.

Option names are case-sensitive
CloudPanel uses camelCase option names:

Code:

--domainName

Code:

--databaseName

Code:

--userName

Code:

--siteUser

Code:

--phpVersion

. Writing

Code:

--domainname

Code:

--database-name

fails. Copy option names from the docs or the cheat sheet instead of typing them.

Error: site or domain not found
Use the site's domain exactly as CloudPanel shows it in the site list: no

Code:

https://

, no trailing slash, and the same

Code:

www

or non-www form. If

Code:

www.example.com

is listed,

Code:

example.com

won't match.

db:import and db:export problems

The file name decides the format:
Code:
.sql.gz
is compressed,
Code:
.sql
is plain.
Import from the folder where the dump is, or give the full path, and make sure the user running the command can read the file (
Code:
ls -l dump.sql.gz
).
Big imports can take minutes. Let them finish; don't start a second one.

Before you script anything
Run the command once by hand and check the result in the panel. Then put it in a cron job or script, and log the output so you can see failures:

Code:

clpctl db:export --databaseName='my_db' --file="/home/siteuser/db-backups/my_db-$(date +%F).sql.gz" >> /home/siteuser/db-backups/export.log 2>&1

Still stuck? Post the exact command (with passwords replaced by XXX), the user you ran it as (

Code:

whoami

) and the full error message.

Sources: CloudPanel: root user commands · CloudPanel: site user commands

More CloudPanel troubleshooting

Applies to CloudPanel v2 on Ubuntu and Debian, October 2026. Replace

Code:

example.com

with your domain and

Code:

siteuser

with your site's user name.