Skip to main content

CLI Basics

The ros2 command-line tool is how you discover, inspect, and interact with a running ROS 2 system without reading anyone's source code. This page covers sourcing the environment correctly and the discovery/inspection commands you will use every day.

Overview​

Every terminal that talks to ROS 2 must first "source" a setup script that puts the right binaries, libraries, and environment variables (ROS_DISTRO, AMENT_PREFIX_PATH, PYTHONPATH, etc.) on your path. Forgetting this step is the single most common reason ros2 commands fail or find nothing.

Why It Matters​

Almost every troubleshooting session starts the same way: "I ran a node but I can't see it anywhere." Before assuming a code or network problem, confirm the environment is sourced and use the ros2 CLI to look at what is actually running. These same commands are used throughout Publisher/Subscriber, Services and Actions, and Troubleshooting.

Core Concepts​

Sourcing the Environment​

A typical ROS 2 install ships a setup script per distro. When you open a new shell , source it manually:

# Underlay (the ROS 2 distro itself) — path and distro name vary by install
source /opt/ros/<distro>/setup.bash

# Overlay (your own workspace, built with colcon) — sourced AFTER the underlay
source ~/ros2_ws/install/setup.bash

Order matters: source the underlay first, then any overlay workspace. Sourcing an overlay makes packages built in that workspace visible, on top of (not instead of) the base distro packages.

Confirm the environment took effect:

printenv ROS_DISTRO
printenv ROS_DOMAIN_ID    # empty/unset is equivalent to 0
which ros2

The ros2 Command Family​

ros2 is a single entry point with sub-commands (verbs) grouped by concept:

ros2 node ...       # nodes
ros2 topic ...       # topics
ros2 service ...     # services
ros2 action ...      # actions
ros2 param ...        # parameters
ros2 interface ...    # message/service/action definitions
ros2 pkg ...           # packages
ros2 run ...            # run a single node
ros2 launch ...          # run a launch file (possibly many nodes)
ros2 bag ...              # record/replay data — see Rosbag
ros2 doctor               # basic environment/network sanity checks

Every sub-command supports --help, which is the fastest way to discover its exact flags:

ros2 topic --help
ros2 topic echo --help

Hands-on Steps​

Start the demo talker so there is something in the graph to inspect (requires the demo_nodes_cpp or demo_nodes_py package, commonly preinstalled with a desktop ROS 2 install):

ros2 run demo_nodes_cpp talker

In a second, sourced terminal, work through discovery:

# 1. Nodes
ros2 node list
ros2 node info /talker

# 2. Topics
ros2 topic list
ros2 topic list -t                 # include the message type
ros2 topic echo /chatter           # print live messages (Ctrl+C to stop)
ros2 topic hz /chatter             # measure publish rate
ros2 topic bw /chatter             # measure bandwidth
ros2 topic info /chatter -v        # publishers, subscribers, and QoS

# 3. Interfaces
ros2 interface show std_msgs/msg/String
ros2 topic type /chatter

# 4. Packages and executables
ros2 pkg list | grep demo_nodes
ros2 pkg executables demo_nodes_cpp

Expected Result​

ros2 node list shows /talker, ros2 topic echo /chatter prints a new String message roughly once per second, and ros2 topic info /chatter -v shows one publisher with its QoS profile. Stop the talker with Ctrl+C when done.

Useful Commands​

# Quick environment and graph sanity check
ros2 doctor
ros2 doctor --report          # more verbose report

# Everything currently running
ros2 node list
ros2 topic list -t
ros2 service list -t
ros2 action list -t

# Inspecting one specific item
ros2 node info <node_name>
ros2 topic info <topic_name> -v
ros2 service type <service_name>
ros2 action info <action_name>

# Interfaces (definitions), not running instances
ros2 interface list
ros2 interface show <package>/msg/<Type>
ros2 interface show <package>/srv/<Type>
ros2 interface show <package>/action/<Type>

Common Problems​

  • ros2: command not found — the environment is not sourced in this shell. Source the distro setup script, then re-check with which ros2.
  • ros2 node list shows nothing, but a node is running — check ROS_DOMAIN_ID matches between the terminal running the node and the terminal running the CLI; see ROS 2 Domain ID and Troubleshooting.
  • A topic appears in ros2 topic list but echo prints nothing — the topic may have no active publisher yet, or a QoS mismatch is silently dropping messages. Check ros2 topic info -v for QoS details and see Troubleshooting.
  • Overlay packages are not found after building — the overlay workspace was built but not sourced in this terminal, or was sourced before the build finished. Re-source install/setup.bash after every colcon build.

Key Takeaways​

  • Source the underlay first, then any overlay workspace, in every new terminal.
  • ros2 <noun> list shows what exists; ros2 <noun> info shows details about one specific item.
  • ros2 interface show shows the definition of a type; ros2 topic echo shows live data.
  • ros2 doctor is a fast first check when something in the environment feels wrong.

Next​

Continue to Workspace and Package to create your own package instead of only inspecting existing ones.