Connect your IDE to CloudBees CD/RO

This guide explains how to connect your IDE to a CloudBees CD/RO server so you can work with CloudBees CD/RO without leaving the IDE.

The connection uses ectool, the CloudBees CD/RO command-line tool, from the IDE’s built-in terminal. The operations you can perform are limited by the permissions granted to your CloudBees CD/RO user account.

What you need

An IDE: Any IDE with a built-in terminal.
ectool: The CloudBees CD/RO command-line tool, in a folder named CloudBeesFlowTools-<version>.
Server address: Looks like cdro.example.com, without the https:// prefix. For example, if your CloudBees CD/RO URL is https://cdro.example.com, enter cdro.example.com.
API token: A long, randomly generated string that authenticates you instead of a password.

There are two ways to connect to CloudBees CD/RO:

Option 1: Use ectool in the IDE terminal
Option 2: Use the CloudBees CD/RO plugin from the IntelliJ IDE

Option 1: Use ectool in the IDE terminal

You can use ectool, the CloudBees CD/RO command-line tool, directly from your IDE’s built-in terminal to connect to a CloudBees CD/RO server and perform operations without leaving the IDE. The operations available to you are governed by the permissions assigned to your CloudBees CD/RO user account.

Download ectool

Use the following steps to download and set up the CloudBees CD/RO command-line tool:

Navigate to CloudBees CD downloads and open the folder for the CloudBees CD/RO release that matches your server version.
Download the file named CloudBeesFlowTools-*.
Extract the downloaded file to a location you can easily access.
Open the bin folder inside the extracted folder. It contains the ectool and ec-groovy executables. For example:
```
/Users/you/Documents/CloudBeesFlowTools-2026.06.0/bin/ectool▼
```
If you are unsure which release your server is running, contact your CloudBees CD/RO administrator.

Create your API token

Follow these steps to create an API token in the CloudBees CD/RO UI:

Navigate to Administration Users.
Select Access tokens from the actions menu of your user account.
Select Create access token.
Complete the following fields on the New access token screen:
1. Name: (Required) Enter a name for the token.
2. Description: Enter a description of the token.
3. Expiration days: Enter the number of days before the token expires.
Select Save changes.

Copy the access token displayed for use.

Treat your API token like a password. Do not email it, share it in chat channels, or store it in shared documents or in project files. If your token is exposed, delete and create a new one. When your token expires, create a new one.

Open the IDE terminal in the ectool folder

Open your IDE’s built-in terminal and do the following:

Navigate to the bin folder from the download step.
Add the bin folder to your system path so you can run ectool from any directory.

Run the login command in the terminal, with your own server and token:

ectool --server cdro.example.com login --token YOUR-TOKEN-HERE▼

Your signed-in session is remembered, so you don’t need to sign in again it for every command. A successful sign-in returns a block of text that includes a sessionId and your userName.

If you do not have an API token available, you can authenticate using your username and password instead. However, using an API token is recommended. An API token is separate from your account password and has its own expiration date.

The following is the exact command, with placeholders:

ectool --server cdro.example.com login YOUR-USERNAME YOUR-PASSWORD▼

Enter your password as plain text, without single or double quotes.

If your password contains special characters, such as & or $, and authentication fails despite entering the correct password, enclose the password in single quotes to prevent the terminal from interpreting these characters.

Option 2: Use the CloudBees CD/RO plugin from the IntelliJ IDE

The CloudBees CD/RO plugin lets you manage jobs, pipelines, releases, and work items from the IDE, and edit and run DSL scripts (Groovy and YAML). The plugin supports CloudBees CD/RO 10.7 and later. It is free, published by CloudBees, and replaces an earlier version listed on JetBrains Marketplace.

Install the plugin

Open a project in IntelliJ IDEA.
Select Settings Plugins from the left pane.
Select Marketplace tab.
Search for CloudBees CD/RO.
Select Install.
Restart the IDE to complete the installation.

The search results may include other plugins with similar names, such as a plugin for Apache Cloudberry. Make sure you install CloudBees CD/RO by CloudBees, Inc. and not those plugins.

You can also download the IntelliJ CloudBees CD/RO plugin from the JetBrains Marketplace and install it manually. For more information, refer to IntelliJ CloudBees CD/RO.

Open the plugin page on the JetBrains Marketplace and download the IntelliJ CloudBees CD/RO plugin.
In IntelliJ IDEA, select Settings Plugins from the left pane.
Select the gear icon and select Install a plugin from disk.
Select a location to install and then follow the prompts to complete the installation.
If prompted, restart IntelliJ IDEA.

Create a token

If you do not have one yet, create an API token as described in Create your API token. Authenticating using a username and password also works, but CloudBees CD/RO recommends using an API token.

Connect to your server

Configure the connection settings for the IntelliJ CloudBees CD/RO plugin to connect to the CloudBees CD/RO server. For more information, refer to Create CloudBees CD/RO IntelliJ IDEA plugin configurations.

If your server uses a private certificate or a proxy, ask your CloudBees CD/RO administrator.

Verify the connection

Once connected, the CloudBees CD/RO panel in IntelliJ IDEA displays a panel with the following details:

Object Type: Filter runs by object type, such as Pipeline.
Launched by: Filter runs by the user who launched them.
Show: Specify the number of runs to display.
Runs table: View the name, status, and start time of each run.

The CloudBees CD/RO console at the bottom of the IDE displays responses received from the server.

For more information, refer to Create CloudBees CD/RO IntelliJ IDEA plugin configurations.

Additional help

To view the full list of ectool commands, run ectool --help.
To view the options for a specific command, run ectool --help <command>. For example, ectool --help modifyStep returns information about the modifyStep command.