# F Prime Command-Line Arguments: Complete Guide to fprime-cli Options

> Master F Prime command-line arguments with our complete guide to fprime-cli options. Interact with flight software efficiently using channels, command-send, and events.

- Repository: [NASA/fprime](https://github.com/nasa/fprime)
- Tags: how-to-guide
- Published: 2026-07-13

---

**F Prime command-line arguments provide a unified interface for interacting with flight software through the `fprime-cli` tool, which supports three positional sub-commands—`channels`, `command-send`, and `events`—each inheriting core transport, dictionary, and logging options while adding specialized flags for telemetry streaming, event monitoring, and command execution.**

The `fprime-cli` utility in the nasa/fprime repository implements a Python-based command-line interface built on the `argparse` library. This tool enables developers to stream telemetry, monitor events, and send commands to flight software instances using a consistent set of command-line arguments across all sub-commands.

## Core Command-Line Options Available in fprime-cli

Every sub-command of `fprime-cli` inherits a base set of options defined in [`fprime-gds/fprime_cli/main.py`](https://github.com/nasa/fprime/blob/main/fprime-gds/fprime_cli/main.py) at line 84. These arguments control transport protocols, dictionary discovery, and logging behavior.

### Transport and Connection Settings

The CLI supports both threaded-TCP sockets and ZeroMQ transport layers. By default, the tool connects to a GDS instance at `127.0.0.1:50050`.

- `--tts-port <PORT>`: Specify the threaded-TCP socket port (default: 50050)
- `--tts-addr <ADDR>`: Set the threaded-TCP socket address (default: 0.0.0.0)
- `--zmq`: Enable ZeroMQ transport instead of threaded-TCP
- `--zmq-server`: Run as a ZeroMQ server (default is client mode)
- `--zmq-transport <in> <out>`: Explicitly set ZMQ inbound/outbound URLs (defaults to IPC sockets)

### Dictionary and Build Configuration

Dictionary files define the command and telemetry structures for your F Prime deployment.

- `-r, --root <DIR>`: Root directory for build artifacts; the CLI searches this location for the application binary and its dictionary
- `--dictionary <FILE>`: Explicit path to a [`Dictionary.json`](https://github.com/nasa/fprime/blob/main/Dictionary.json) file, overriding automatic search
- `--packet-spec <FILE>`: Path to a packet specification file

### Logging and Output Control

Configure where and how the CLI records session data.

- `-l, --logs <DIR>`: Directory for log files (created if missing)
- `--log-directly`: Use the log directory directly without creating dated sub-folders
- `--log-to-stdout`: Echo log output to the console in addition to files
- `--file-storage-directory <DIR>`: Directory for uplink/downlink file storage (default: `/tmp/fprime-downlink/`)

## Sub-Command Specific Arguments

The three positional sub-commands—`channels`, `events`, and `command-send`—each append specialized flags to the core options.

### channels

Stream telemetry channel values from the flight software.

- `--list`: Display all available channel types
- `-i, --ids`: Filter by specific channel IDs
- `-c, --components`: Filter by component names
- `-s, --search`: Search channels by name pattern
- `-t, --timeout`: Set collection timeout
- `-j, --json`: Output in JSON format

### events

Stream recorded events from the flight software. This sub-command accepts the same filtering flags as `channels`.

- `--list`, `-i/--ids`, `-c/--components`, `-s/--search`, `-t/--timeout`, `-j/--json`

### command-send

Send commands to the flight software with support for command arguments.

- `command-name`: Positional argument specifying the command to send
- `--arguments` or `-args`: Supply command arguments as a list
- `--list`, `-i/--ids`, `-c/--components`, `-s/--search`, `-j/--json`: Same filtering and output options as other sub-commands

## Dictionary Auto-Discovery Mechanism

When invoked without the `--dictionary` flag, `fprime-cli` automatically scans the current working directory for files ending in [`Dictionary.json`](https://github.com/nasa/fprime/blob/main/Dictionary.json). If the tool fails to locate a valid dictionary, it aborts with the error message "No valid project dictionary found". Supplying an explicit path via `--dictionary <PATH>` bypasses this discovery mechanism entirely, allowing you to target specific build artifacts.

## Practical Usage Examples

Here are common patterns for interacting with F Prime flight software using `fprime-cli`.

Display top-level help showing core options:

```bash
fprime-cli -h

```

List all available telemetry channels using auto-detected dictionary:

```bash
fprime-cli channels --list

```

Stream telemetry from a specific component filtered by name:

```bash
fprime-cli channels -c pingRcvr -s TEMP

```

Stream events in JSON format for downstream processing:

```bash
fprime-cli events -j

```

Send a command with arguments (example: changing ping period to 50ms):

```bash
fprime-cli command-send health.HLTH_CHNG_PING --arguments eventLogger 50 20

```

Point to a specific dictionary in a non-standard build location:

```bash
fprime-cli command-send cmdDisp.CMD_NO_OP \
    --dictionary build-artifacts/Linux/Ref/Top/RefTopologyDictionary.json

```

Connect to a remote GDS instance on a custom port:

```bash
fprime-cli events --tts-port 60000 --tts-addr 192.168.1.42

```

## Implementation Details

The command-line interface architecture is implemented across several key files in the `fprime-gds` package:

- [`fprime-gds/fprime_cli/main.py`](https://github.com/nasa/fprime/blob/main/fprime-gds/fprime_cli/main.py): Implements the top-level `argparse` parser and wires sub-commands at line 84
- [`fprime-gds/fprime_cli/commands.py`](https://github.com/nasa/fprime/blob/main/fprime-gds/fprime_cli/commands.py): Contains the concrete logic for `channels`, `events`, and `command-send`
- [`fprime-gds/fprime_cli/util.py`](https://github.com/nasa/fprime/blob/main/fprime-gds/fprime_cli/util.py): Provides helper utilities for dictionary discovery and GDS connection handling
- [`docs/user-manual/gds/gds-cli.md`](https://github.com/nasa/fprime/blob/main/docs/user-manual/gds/gds-cli.md): Documents the full user-visible help text and argument reference

## Summary

- **Core transport options** (`--tts-port`, `--tts-addr`, `--zmq`) are shared across all sub-commands and defined in [`fprime-gds/fprime_cli/main.py`](https://github.com/nasa/fprime/blob/main/fprime-gds/fprime_cli/main.py)
- **Three sub-commands** (`channels`, `events`, `command-send`) provide specialized functionality for telemetry, event monitoring, and command execution
- **Dictionary discovery** happens automatically by searching for [`Dictionary.json`](https://github.com/nasa/fprime/blob/main/Dictionary.json) files, or can be overridden with `--dictionary`
- **Default connection** targets `127.0.0.1:50050` using threaded-TCP sockets
- **Filtering capabilities** (`--list`, `--search`, `--components`) allow precise targeting of telemetry and commands

## Frequently Asked Questions

### What is the default port for fprime-cli connections?

By default, `fprime-cli` connects to the Ground Data System (GDS) on port 50050 at address 127.0.0.1. You can override these values using the `--tts-port` and `--tts-addr` options to connect to remote instances or custom ports.

### How does fprime-cli find the dictionary file?

The tool automatically searches the current working directory for files ending in [`Dictionary.json`](https://github.com/nasa/fprime/blob/main/Dictionary.json). If no dictionary is found, the CLI aborts with the error "No valid project dictionary found". Use the `--dictionary` flag to specify an explicit path to the dictionary file.

### Can I use ZeroMQ instead of TCP with fprime-cli?

Yes. Pass the `--zmq` flag to enable ZeroMQ transport instead of the default threaded-TCP socket. You can also use `--zmq-server` to run as a server (default is client) and `--zmq-transport` to specify custom inbound and outbound URLs.

### How do I send a command with arguments using fprime-cli?

Use the `command-send` sub-command followed by the command name and the `--arguments` (or `-args`) flag. For example: `fprime-cli command-send health.HLTH_CHNG_PING --arguments eventLogger 50 20`. The arguments flag accepts the command parameters as a space-separated list.