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, you do not need to add an environment. By default, an environment named "workbench" is created after installing the Control-M Automation CLI. Continue to next step.

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

All commands invoked will use the default environment. 

For Control-M Workbench:

ctm environment set workbench

For Control-M instance:

The following example command shows how to set an environment named devEnvironment as your default environment. 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