Using the CLI

The ouster-cli tool provides a command line interface to interact with Ouster sensors and data.

Install the ouster-sdk python package to get access to the ouster-cli utility. See Ouster SDK Installation for installation instructions.

After installation, to verify installation and view command options, open a terminal and run:

ouster-cli --help

Collecting Metadata

Sensor metadata, necessary for interpreting and parsing the pcap data, can be collected from sensors using:

ouster-cli source {VALID_INPUT_SOURCE} sensor_info > {SENSOR_HOSTNAME}.json

This will generate a .json file named {SENSOR_HOSTNAME}.json with the metadata inside. To output it to a differently named file, simply change {SENSOR_HOSTNAME}.json to {FILL_IN_ALTERNATE_NAME}.json.

You can also print the metadata to screen by removing > and everything after it in the command.

Load sensor source

The source command selects the sensor or recording that subsequent commands operate on. Run ouster-cli source --help to see the available options and subcommands. After the source is bound, chain whichever consumer you need such as stats, viz, or save.

Inspect a live sensor directly from the terminal:

ouster-cli source {SENSOR_HOSTNAME} stats --verbose

By default, running ouster-cli source {SENSOR HOSTNAME} will reconfigure the sensor to transmit lidar packets to the host running ouster-cli and reinitialize the sensor.

One can disable the default reinitialization/UDP destination behavior or adjust timeouts before launching the visualizer as mentioned below:

ouster-cli source -x -y --timeout 2 {SENSOR_HOSTNAME} viz

Remember that you can use --help with any ouster-cli subcommand, regardless how far down the menu tree you are.

Ubuntu UFW Firewall may cause: No packets received within 1.0s

On some Ubuntu setups we’ve observed the situations when everything is configured properly so that:

  • sensor is seen on the network and its Web page can be reached

  • sensor destination IP is set to the IP of the computer where data is expected

  • sensor lidar port is known (i.e. default 7502, or some others)

  • sensor is in RUNNING state

  • sensor lidar packets traffic is seen on the expected machine and can be recorded with tcpdump -w command to a pcap file (or Wireshark tools)

  • CLI command ouster-cli source <SENSOR HOSTNAME> {info,config} are working properly

  • Viz ouster-cli source <PCAP FILE> viz from the tcpdump recorded pcap can be played and visualized

But ouster-cli source <SENSOR HOSTNAME> viz, or ouster-cli source <SENSOR HOSTNAME> save still can’t receive any packets and get the following error:

ouster.sdk.core.ClientTimeout: No packets received within 1.0s

Please check your UFW Firewall settings and try to allow the UDP traffic for 7502 (or whatever the UDP Port Lidar is set on the sensor):

sudo ufw allow 7502/udp

Replay

Use info to summarise a captured pcap/osf/bag/mcap file or dataset:

ouster-cli source {SAMPLE_DATA_PCAP_PATH} info

For pcap, if the metadata lives in a separate JSON file, pass it with --meta so the CLI can associate the correct calibration and configuration with the capture:

ouster-cli source --meta {SAMPLE_DATA_JSON_PATH} {SAMPLE_DATA_PCAP_PATH} info

Opening Recordings from Ouster Studio

The source command also accepts links to recordings hosted on Ouster Studio . When the source is a studio.ouster.com link, the CLI resolves it to the recording’s OSF file and then operates on it like any local OSF file, so you can chain the usual consumers (info, viz, save, …):

ouster-cli source "https://studio.ouster.com/share/V96PNUOMAATVXPPB" viz

Two kinds of links are supported:

  • Share links (those containing /share/) are public and require no authentication.

  • Drive links require you to be signed in to your Ouster organization. The first time you open one, the CLI opens a browser window to complete authentication; the resulting credentials are cached under ~/.config/ouster/ so subsequent commands do not prompt again.

Only recordings that expose an OSF output file can be opened this way — the CLI selects the OSF output and ignores other available formats.

Single Sensor Options

If required, one can restrict processing to a single sensor index. This is the CLI equivalent of the sensor_idx parameter (and the underlying single() method) in the API; see open_source Parameters for how single-sensor selection works.

ouster-cli source --sensor-idx 0 {SAMPLE_DATA_PCAP_PATH} stats

Multi Sensor Options

Provide a comma-separated list of sensor hostnames to operate on multiple live sensors at once:

ouster-cli source {SENSOR_HOSTNAME},{SENSOR_HOSTNAME2} stats

When replaying files, combine --glob with a pattern to iterate through compatible captures:

ouster-cli source --glob "{OSF_GLOB}" stats

Field Selection

The --fields option mirrors the SDK APIs that request specific channel fields. Combine it with --filter to drop incomplete frames while computing stats or piping data to other consumers:

ouster-cli source --fields RANGE,REFLECTIVITY --filter {SAMPLE_DATA_OSF_PATH} stats