cPanel® Blog

cPanel’s command line API tools

In cPanel & WHM version 11.52 we released command line utilities for WHMAPI0 and WHMAPI1. In v56 we have added command line utilities for the cPanel UAPI, cPanel API 1, and cPanel API 2 as well. All of these are meant to help any user, whether root/reseller or a cPanel user, interact with and test API functions more easily. This will also make adjusting user, account, server, and service settings much easier, and helping to reduce reliance on third party applications like Puppet and Ansible. Overall, as we will see, these tools lead to less time and effort at every step. 

How to use the Command Line API utilities

Historically, using the API on any cPanel & WHM server required the user to create a complex script, with many potential spots for human error. The command line API utilities are very simple and straight forward to use, and significantly reduce the effort required to interact with cPanel & WHM’s APIs. As root, you have access to both cPanel’s APIs, and WHM’s APIs. For example, if you wanted to use the UAPI call to see the Site Template settings for an account with username benny, you would use the SiteTemplates function and run this command:

[root@v56 ~ ]$ uapi --user=benny SiteTemplates list_user_settings
---
apiversion: 3
func: list_user_settings
module: SiteTemplates
result:
  data:
    -
      documentroot: /home/benny/public_html
      domain: benny.com
      homedir: /home/benny
      serveralias:
        - www.benny.com
      template_settings:
        businessHours: 1-7am
        businessHoursNotes: Closed weekends
        businessName: benny's business
        description: This site is pretty nifty.
        descriptionSectionHeader: other stuff
        docroot: /home/benny/public_html
        domain_url: http://benny.com
        emailAddress: benny@benny.com
        facebookLink: ''
        faxNumber: ''
        googleMapsURL: ''
        google_analytics_key: ''
        is_empty: 0
        linkedinLink: ''
        path: /usr/local/cpanel/etc/site_templates
        phoneNumber: ''
        physicalAddress: ''
        tagLine: stuff
        template: business
        twitterLink: ''
      type: main_domain
  errors: ~
  messages: ~
  metadata:
    transformed: 1
  status: 1
[root@v56 ~ ]$

cPanel users could run the same command by simply removing the flag identifying the user:

[benny@v56 ~]$ uapi SiteTemplates list_user_settings            .
---
apiversion: 3
func: list_user_settings
module: SiteTemplates
result:
  data:
    -
      documentroot: /home/benny/public_html
      domain: benny.com
      homedir: /home/benny
      serveralias:
        - www.benny.com
      template_settings:
        businessHours: 1-7am
        businessHoursNotes: Closed weekends
        businessName: benny's business
        description: This site is pretty nifty.
        descriptionSectionHeader: other stuff
        docroot: /home/benny/public_html
        domain_url: http://benny.com
        emailAddress: benny@benny.com
        facebookLink: ''
        faxNumber: ''
        googleMapsURL: ''
        google_analytics_key: ''
        is_empty: 0
        linkedinLink: ''
        path: /usr/local/cpanel/etc/site_templates
        phoneNumber: ''
        physicalAddress: ''
        tagLine: stuff
        template: business
        twitterLink: ''
      type: main_domain
  errors: ~
  messages: ~
  metadata:
    transformed: 1
  status: 1
[benny@v56 ~]$
Attempting to run any of the WHMAPI calls as a user will result in a clear error. For example, trying to check on cPHulk’s status as a user looks like this:
[benny@v56 ~]$ whmapi1 cphulk_status                            .
[whmapi1] This program can only be run by root!
whmapi1
Utility to execute WHM api calls
       whmapi1 [function] [key=value] [key=value] ....
       --output=[json|jsonpretty|xml|yaml]
             The serialization format to use for output.
       --help Prints this help text.
[benny@v56 ~]$
While running the same command as root gets you the information you desire:
[root@v56 ~ ]$ whmapi1 cphulk_status                            .
---
data:
is_enabled: 1
service: cPHulk
metadata:
command: cphulk_status
reason: OK
result: 1
version: 1
[root@v56 ~ ]$

Where to go for help

cPanel’s documentation team works very hard to make all of our documentation outstanding, and the Software Development Kit (SDK) is no exception. You’ll see documentation provided there for each of our support APIs, as well as the historical documentation for our deprecated APIs, and each function has its own example in multiple programming languages.

If you can’t find what you need there, or are having trouble with it, cPanel’s forums are a great next step. Take a look at the tutorials there, open up a thread with any questions you have. If you still aren’t finding the help you need, email me or find me on twitter. I’ll get you squared away!

benny Vasquez

scripter, crafter, cPanel’s Manager of Community Engagement. Facilitating communication between cPanel’s amazing development team, and cPanel’s amazing community. Find me on twitter: @cpaneldev

  • Monarobase

    Will users be able to use this to autmate a daily backup to an external FTP account ?
    Currently users without reseller access have to run a complicated script that connects to cPanel using curl to request a full backup. If they could use uapi in a cron to request a full backup it would make things much easier…

    • cPanelbenny

      They definitely should be able to! If you want to send me the script you’re using ( benny@cpanel.net ), I should be able to take a look and see what we can do to simplify it.