Tutorials - Setting up the prerequisites

The following steps describe how to set up your environment to run the various tutorials.

Step 1 - Clone the GitHub repository

Fetch tutorial samples from GitHub and run git clone to create a local copy of the source code.

git clone https://github.com/controlm/automation-api-quickstart.git


If you do not yet have Git installed, obtain it from the Git Downloads page.

Step 2 - Obtain access to Control-M Automation API

Control-M Automation API is a REST API interface over HTTPS. You can either install Control-M Workbench or access a Control-M instance where you must have Control-M credentials.

Step 3 - Install Control-M Automation CLI

To run the tutorials you need a working Control-M CLI. Refer to the Control-M Automation CLI installation guide. Follow the steps for the relevant platform.

Step 4 - Set up a Control-M environment

The Control-M Automation CLI requires an environment to run the commands. An Environment is a combination of an endPoint, username, and password.

An endPoint is the URI for Control-M Automation API. The endpoint has the following format:


If you installed Control-M Workbench, use the following command to add an environment for the Workbench:

ctm environment workbench::add

If you accessed a Control-M instance, use the following command to add an environment. In this example, the environment is named devEnvironment:

ctm environment add devEnvironment "https://<controlmEndPointHost>:8443/automation-api" "[ControlmUser]" "[ControlmPassword]"


While the environment is added, it is checked for its policy regarding certificates. If the environment is currently set to accept self-signed certificates, a warning is displayed. If you want to apply a stricter policy of accepting only certificates signed by a trusted Certificate Authority (and not accepting self-signed certificates), you can use the ctm environment configure command to set the rootCertificateRequired parameter to true.

Step 5 - Set the environment as default

When you set up your first environment, it is automatically set as the default environment that is used by any API commands that you invoke. In such a case, you can skip this step. Later, after defining additional environments, perform this step to set the default environment of your choice.

In the following example, the Control-M Workbench is set as the default environment. The returned response lists the single environment that is currently defined and notifies you that it is set as the default environment.

> ctm environment set workbench

info:    current environment: workbench
info:    environments: {
  "workbench": {
    "endPoint": "https://localhost:8443/automation-api",
    "user": "workbench"

In the following example, devEnvironment (a Control-M instance) is set as the default environment, and the returned response lists all existing environments.

> ctm environment set devEnvironment

info:    current environment: devEnvironment
info:    environments: {
  "local": {
    "endPoint": "http://localhost:48080/",
    "user": ""
  "devEnvironment": {
    "endPoint": "https://<controlmEndPointHost>:8443/automation-api",
    "user": "<controlmUser>"


After setting the default environment, if you want to run API commands against a different, non-default environment, you must include the -e <environmentName> option in any API command that you run. In addition, ensure that the version of the destination environment matches the version of the CLI.

Step 6 - Verify the setup by logging in to a session

After setting up the Control-M environment for the CLI, ensure that the user associated with the default environment can successfully log in to a CLI session. For a workbench environment, the user is named workbench. For any other Control-M environment, the user is specified during environment setup.

To log in to a CLI session, use the Session Service. The response returns the user name, a token for the session, and the version of the CLI, as shown in the following example:

> ctm session login

  "username": "emuser",
  "token": "d6ad05ecbee1dd74bf100447ed2be5d6_D749761E",
  "version": "9.18.2"

Step 7 - Access documentation

You can access the REST API documentation for this environment:

ctm documentation restApi

To access this web-based API documentation:

ctm doc gettingStarted
Was this page helpful? Yes No Submitting... Thank you


  1. Martin Lueken

    I like to use the REST API without the CLI. I just want to connect from SOAPUI to my REST server. How do I do this????

    Mar 06, 2019 09:26
    1. Yechezkel Schatz

      Thanks, Martin, for the inquiry. I'm working with the Dev team to figure out all the technical details and how to include the missing information here in the documentation. I'll keep you posted.

      Mar 06, 2019 10:38
    1. Yechezkel Schatz

      I understand that BMC Support has been in touch with you and have sent you a REST-based example through Github. Please let me know if you need anything else.

      Mar 13, 2019 08:20
      1. Ionut Moise

        Hi Yechezkel, Can this information be made public. I guess all of would like to skip using the CLI and use the REST API directly. Thank you!

        Mar 14, 2019 07:28
      1. Jaume Llarden

        I second Ionut's request on making that information public. Some directions/tutorials/examples on how to use the REST API directly would be greatly appreciated.

        Jun 02, 2019 04:52
      1. Yechezkel Schatz

        The Control-M Automation API Community in https://github.com/controlm is a great platform for finding and sharing samples and examples similar to the one you inquired about. Let me know if you see anything relevant there.

        Jun 03, 2019 09:56
  2. Jaume Llarden

    I installed the Control-M Workbench OVA file on VMWare Fusion running on macOS Mojave, and noticed that this command:

    ctm environment workbench::add

    added the wrong environment (the endPoint URL points to localhost instead of the Workbench IP address):

    Environment 'workbench' was created
    workbench: {"endPoint":"https://localhost:8443/automation-api","user":"workbench"}

    For anyone running into the same problem, I had to delete the environment:

    ctm environment delete workbench

    and add it providing the correct URL:

    ctm environment workbench::add https://<Workbench IP address>:8443/automation-api
    Jun 02, 2019 04:45