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

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 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 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. 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:

fprime-cli -h

List all available telemetry channels using auto-detected dictionary:

fprime-cli channels --list

Stream telemetry from a specific component filtered by name:

fprime-cli channels -c pingRcvr -s TEMP

Stream events in JSON format for downstream processing:

fprime-cli events -j

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

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

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

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:

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: Implements the top-level argparse parser and wires sub-commands at line 84
• fprime-gds/fprime_cli/commands.py: Contains the concrete logic for channels, events, and command-send
• fprime-gds/fprime_cli/util.py: Provides helper utilities for dictionary discovery and GDS connection handling
• 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
• 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 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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}