How to run Control-M Report from command line using Control-M Automation API?

Version 2
    Share This:

    This document contains official content from the BMC Software Knowledge Base. It is automatically updated when the knowledge article is modified.


    Control-M/Enterprise Manager


    Control-M/Enterprise Manager


    Control-M/Enterprise Manager v9.0.18 Control-M Report


    How to run Control-M Report from command line using Control-M Automation API?


    Running Control-M Report via Control-M Automation API
    Step 1:

      Control-M Automation CLI   (Taken from : CLI installation  ) 
      Installation instructions for the Control-M Automation Command Line Interface (CLI) are provided separately for each of the following platforms:
      Installation for Windows 
      Step 1.1   - Install or Upgrade Node.js   (Install Globally)
    • Using a browser, download the Node.js Windows Installer from
    • Run the installer and follow the instructions on screen. 
    • The Node.js installer includes the npm (Node Package Manager) utility. For requirement details, see CLI Requirements. Verify that you have the required version installed by entering the following commands into a command prompt, as shown in this example:
      >node -v
    >npm -v
      Some Node.js installers include npm version 2.x or below. To upgrade npm, use the following command: 
      >npm -g install npm@latest
      Step 1.2 - Download Command Line Interface (CLI)
      Download a ctm-cli.tgz node package from the following location:
          Control-M Workbench    
            Click Download from 
          Control-M instance    
      Step 1.3 - Install the CLI   (Install Globally)
      To install the ctm-cli.tgz node package, run cmd, and then type the following command from the directory where you saved the ctm-cli.tgz file: 
      >npm -g install ctm-cli.tgz

    Please take note even though we recommend that the CLI is installed as a global user on the machine but it does not imply that the environment is shared for all the users other than all users will have access to the binaries. As such if you wants to install it globally please apply below procedures. 
        1. Open an administrator level command prompt 
       2. Note the current global prefix: npm prefix -g 
              For example user will get someting like:C:\Users\<username>\AppData\Roaming\npm 
        3. Set the global prefix to a common path accessible by all:
             mkdir %PROGRAMDATA%\npm
           setx PATH "%PROGRAMDATA%\npm;%PATH%" /M
    npm config set prefix %PROGRAMDATA%\npm
     Install package: npm i -g ctm-cli.tgz 
       5. Restore the prefix to the previous value
               npm config set prefix C:\Users\<username>\AppData\Roaming\npm
            where  <username> is customer login user. 
      Step 1.4- Test the CLI Installation
      Run the following command through a command prompt: 
    help:    Display help for a given command
    help:      help [command]
    help:    Commands:
    help:      build            Compile definitions to verify they are valid for Control-M
    help:      config           Configure the Control-M environment
    help:      deploy           Submit definitions to Control-M
    help:      documentation    Get documentation
    help:      environment      Define and select the Control-M environment
    help:      package          Package a directory of definition files into a deployable archive
    help:      provision        Install Control-M components
    help:      reporting        Generate Control-M reports
    help:      run              Run and track Control-M jobs
    help:      samples          Manage data samples
    help:      session          Manually maintain Control-M user sessions
    help:    Options:
    help:      -h, --help     output usage information
    help:      -v, --version  output the application versio
      Step 1.5 - Install Java for the provision service
    • Using a browser, download the Java Windows Installer from
    • Follow the instructions for Windows 64-bit
    • For requirement details, see CLI Requirements. Verify that you have the required version and environment variable set as shown in this example:
      >"%JAVA_HOME%"\bin\java -version
    java version "1.8.0_20"
    Java(TM) SE Runtime Environment (build 1.8.0_20-b26)
    Java HotSpot(TM) 64-Bit Server VM (build 25.20-b23, mixed mode)
      From <>
       Step 2:   
      Moving on to the systems environmental settings: 
      Step 2.1: Since the Default environment "workbench" is arriving with the user: workbench I usually add another environment definition:
      ctm env add env1 https://<controlmEndPoint>:8443/automation-api emuser empass 
      User-added image 
      Step 2.2: Set the new environment as your working environment: 
      ctm env set env_1 
      User-added image 
      Step 2.3: Verify that the new user can login: 
      ctm session login 
      User-added image 
      Step 2.4: Verify report generation manually via ctm cli  
    In order to run ctm reporting command, make sure the user defined the ctm cli environment is same user that defined the Control-M report in the Control-M/Enteprise Manager Workload Automation client GUI
    Else will receive an error "failed to get report <ReportName> " which is described in Knowledgebase Article # 000148073
      Now you should be good for setting the reports: 
      ctm reporting report::get Sample_Report   pdf  -o C:\ExportDir\Sample_Report.  pdf 
      User-added image 
      And for CSV: ctm reporting report::get Sample_Report csv -o C:\ExportDir\Sample_Report.csv 
      User-added image
       Step 3:   
      Setting an OS job to run a Control-M Report:   
    • Use the above command and add it to your OS Job
    • To add a date and/or time stamp to the file name of the report, the relevant Control-M System Variables can be used in the file name specified after the "-o" option in the Control-M job.      
      User-added image 
      For already installed environment the Run AS user would probably already be set correctly. 
      In case they are not please make sure that the Job is using a Run as user that is indeed used by the Agent, and has sufficient privileges to execute on the agent machine.  
      In the Lab - Follow the below steps:   
    • Set the Run as field to the user with which you log in to the machine (In our example - Run as Vagrant as can be seen in the above example)
    • Set the user with which you log in to the machine to be the one used by the agent (Below item # 1)
        User-added image 
    3.       Make sure that the    user with which you log in to the machine is authorized through the CCM  
        User-added image 
      This information is summarized in the following video: 

    Additional Information:
    Customers viewing this solution may find value in the following self-help Connect with Control-M video.



    Article Number:


    Article Type:


      Looking for additional information?    Search BMC Support  or  Browse Knowledge Articles