The ROS Command Line Interface (CLI)

5. The ROS Command Line Interface (CLI)#

The ROS command line interface, or CLI for short, is a set of programs for starting, inspecting, controlling, and monitoring a ROS robot. The best way to think of the CLI is a collection of small and simple programs that allow you perform basic tasks in ROS. Drawing from our car analogy, the CLI can be thought of as the subsystems of a vehicle: the breaks, the transmission, the window wipers, all of the smaller parts that are composed together to build the larger vehicle. What we’ll show you in this section is how to turn on the car, put it in gear, turn on the radio, and perhaps check your oil to perform routine maintenance. The ROS 2 CLI draws heavily from the Unix/Linux philosophy of small programs that can be composed together. If you are familiar with the command line interface found in Unix and Linux, or to a lesser extent in MacOS or Windows, you’ll feel right at home.

The ROS command line tools draw heavily from the design patterns mentioned in the previous section, and directly interface with the APIs we will address in the next section. The CLI is at its core just a set of simple tools built from the ROS 2 API; this API is simply an implementation of the high-level patterns we discussed in the previous section. If your goal is to simply interface with a particular piece of software written using ROS, the CLI is the way you will go about starting, stopping, and controlling the underlying ROS software. For more advanced users these tools will allow you to study a ROS system by exploring the underlying software processes in the system.

There are only two things you need to memorize from this section. The first command simply tells your computer that you are using ROS by sourcing your ROS environment (explained next), and what version of ROS you want to use. The other command you need to commit to memory is ros2, the starting point of every step when working with ROS 2 in the terminal.

5.1. Sourcing your ROS environment#

Before we can use the CLI, don’t forget to run the magic command to ensure the ROS Workspace is accessible in your terminal.

$ source /opt/ros/humble/setup.bash

Warning

Don’t forget, in every terminal you open you must source the ROS workspace you want to use! Otherwise, you will not be able to run ROS 2 CLI commands in that terminal.

You should plan on doing this every time you want to use ROS. The most common mistake new users have is not running this command.

If you’re not sure if you ran the command in a shell, that’s okay. The command is idempotent: running it twice in a row won’t break anything. You can run it a million times in a row and it won’t make any difference.

If everything is working correctly, this command should simply return. Nothing happens that you can see, but underneath the hood you’ve just told this particular shell that you are using ROS 2 Humble and where all the ROS programs and files live.

5.2. First steps with the CLI#

Almost everything in the ROS 2 CLI starts with ros2. Go ahead and try it in the same shell where you just sourced the setup file. If everything is working correctly you should see the following:

$ ros2
usage: ros2 [-h] Call `ros2 <command> -h` for more detailed usage. ...

ros2 is an extensible command-line tool for ROS 2.

optional arguments:
  -h, --help            show this help message and exit

Commands:
  action     Various action related sub-commands
  component  Various component related sub-commands
  daemon     Various daemon related sub-commands
  doctor     Check ROS setup and other potential issues
  interface  Show information about ROS interfaces
  launch     Run a launch file
  lifecycle  Various lifecycle related sub-commands
  msg        Various msg related sub-commands
  multicast  Various multicast related sub-commands
  node       Various node related sub-commands
  param      Various param related sub-commands
  pkg        Various package related sub-commands
  run        Run a package specific executable
  security   Various security related sub-commands
  service    Various service related sub-commands
  srv        Various srv related sub-commands
  topic      Various topic related sub-commands
  wtf        Use `wtf` as alias to `doctor`

  Call `ros2 <command> -h` for more detailed usage.

From this one command you can figure out what every single ROS 2 CLI program does and how to use it. The ROS 2 CLI has a syntax just like most languages. All ROS CLI commands start with ros2, followed by a command. After the command any number of other things can come; you can append --help or -h to see the documentation and find out what arguments any of the commands are expecting. The rest of this section just walks through each of the commands one by one.

Tip

Save yourself time and errors when working with the terminal!

Writing commands using the command line is tricky and error prone. There are a couple of tools you can use to make the process much smoother. The first is the TAB key, which attempts to auto complete whatever you type. It can’t read your mind, but for common command combinations you usually only need to type the first one or two letters. Another tool is the up arrow key. When you use the command line sometimes you mistype a command or need to rerun a command. Pressing the up key will cycle through the previous commands which you can modify and rerun as needed.

Note

The ROS 2 CLI is actively being developed, which means the available commands, their sub commands, and the optional arguments tend to grow with each new ROS release.

At various stages in this manual we show you some ros2 <command> --help output. Be aware that the shown help info on your terminal could be more extensive than what we show in this manual. Don’t worry about this difference, all the main commands should still be available!

5.3. Summary#

We have seen that:

  • In every bash shell where you want to use ROS 2 you need to source ROS’s setup.bash, otherwise the ROS 2 CLI commands will not be available.

  • The main entry point for nearly all ROS 2 CLI commands is the ros2 command, which has various sub commands. You can use the --help flag to get more option on this command and its sub commands.

In the next sections of this chapter we will use the CLI to explore the various concepts discussed before in Section 4.