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 straightforward 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 the command below. If you are using CloudLinux, you need to use the full path: /usr/local/cpanel/bin/uapi

[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.

Header image courtesy of ToolsAreHome.com.