CLI Reference
The rosfit CLI gives you full control over your RosFit platform from the terminal — initialize projects, manage devices, stream telemetry, send commands, deploy firmware, and provision TLS certificates.
Installation
pip install rosfit-cli
Or install from source:
git clone https://github.com/rosfit/rosfit.git
cd rosfit/cli
pip install -e .
Verify the installation:
rosfit --version
# rosfit-cli 1.2.0
Configure your default endpoint and credentials:
rosfit config set api_url http://localhost:8000/api/v1
rosfit config set api_key rft_live_a1b2c3d4e5f6
rosfit init
Initialize a new RosFit project in the current directory. Creates a rosfit-bridge.yaml configuration file and an .env file with sensible defaults.
rosfit init
| Flag | Default | Description |
|---|---|---|
--name | directory name | Project name |
--device-type | ros2_robot | Device type (ros2_robot, micro_ros_mcu, mqtt_device, gateway) |
--broker | localhost:1883 | MQTT broker address |
--tls | false | Enable TLS for MQTT connection |
--template | default | Config template (default, turtlebot3, esp32, rpi) |
Example with flags:
rosfit init --name warehouse-bot --device-type ros2_robot --broker emqx.rosfit.local:8883 --tls
This generates a rosfit-bridge.yaml pre-configured for your setup.
rosfit connect
Start the bridge process and connect to the MQTT broker. Reads configuration from rosfit-bridge.yaml in the current directory or the path specified by --config.
rosfit connect
| Flag | Default | Description |
|---|---|---|
--config | ./rosfit-bridge.yaml | Path to bridge config file |
--daemon | false | Run as a background daemon |
--log-level | info | Log verbosity (debug, info, warn, error) |
--retry | true | Auto-reconnect on connection loss |
rosfit connect --config /etc/rosfit/bridge.yaml --daemon --log-level debug
rosfit devices
Manage devices registered on the platform.
rosfit devices list
rosfit devices list
| Flag | Description |
|---|---|
--status | Filter by status (online, offline, error, provisioning) |
--type | Filter by device type |
--group | Filter by group |
--format | Output format (table, json, csv) |
rosfit devices list --status online --format table
DEVICE ID NAME TYPE STATUS GROUP LAST SEEN
dev_k8m2n4 turtlebot-01 ros2_robot online warehouse-east 2s ago
dev_p5q6r7 arm-controller ros2_robot online assembly-line 5s ago
dev_s8t9u0 sensor-node-03 mqtt_device online greenhouse 12s ago
rosfit devices add
Register a new device interactively or with flags:
rosfit devices add --name "forklift-02" --type ros2_robot --group warehouse-west --tag amr --tag heavy-lift
The command prints the device ID and MQTT token on success.
rosfit devices info
Show detailed information for a device:
rosfit devices info dev_k8m2n4
rosfit devices remove
Decommission a device:
rosfit devices remove dev_old_unit --confirm
rosfit monitor
Stream live telemetry from a device to the terminal with real-time formatting.
rosfit monitor dev_k8m2n4
| Flag | Default | Description |
|---|---|---|
--topics | all | Comma-separated list of topics to monitor |
--format | pretty | Output format (pretty, json, raw) |
--rate | 10 | Maximum messages per second |
--duration | indefinite | Stop after N seconds |
rosfit monitor dev_k8m2n4 --topics odom,battery_state --format json --rate 5
Output:
{"topic": "odom", "timestamp": "2026-03-30T10:05:32Z", "position": {"x": 12.4, "y": 3.7}}
{"topic": "battery_state", "timestamp": "2026-03-30T10:05:33Z", "percentage": 78.2}
rosfit send
Send a command to a device.
rosfit send dev_k8m2n4 navigate_to '{"goal": {"position": {"x": 5.0, "y": 3.0}}}'
| Flag | Default | Description |
|---|---|---|
--timeout | 60 | Command timeout in seconds |
--wait | false | Block until command is acknowledged |
--priority | normal | Priority level (low, normal, high, critical) |
rosfit send dev_k8m2n4 emergency_stop '{}' --priority critical --wait
# Command cmd_p3q4r5 acknowledged in 0.23s
Broadcast to a group:
rosfit send --group warehouse-east emergency_stop '{}' --priority critical
rosfit logs
Stream or query logs from a device.
rosfit logs dev_k8m2n4
| Flag | Default | Description |
|---|---|---|
--follow / -f | false | Follow log output in real-time |
--since | 1h | Show logs since duration (5m, 1h, 24h) |
--level | all | Filter by log level (debug, info, warn, error) |
--search | — | Full-text search within logs |
rosfit logs dev_k8m2n4 -f --level error --since 24h
2026-03-30 09:12:03 [ERROR] Navigation failed: obstacle detected at (4.2, 7.1)
2026-03-30 09:45:17 [ERROR] LIDAR timeout: no scan data for 5s
rosfit deploy
Deploy firmware to devices via OTA.
rosfit deploy firmware-v2.2.0.bin --version 2.2.0 --target dev_k8m2n4
| Flag | Default | Description |
|---|---|---|
--version | — | Firmware version string (required) |
--target | — | Device ID or group name |
--strategy | rolling | Deployment strategy (rolling, all-at-once, canary) |
--max-concurrent | 5 | Max simultaneous updates |
--rollback-on-failure | true | Auto-rollback on failed update |
--dry-run | false | Simulate deployment without executing |
rosfit deploy firmware-v2.2.0.bin --version 2.2.0 --target warehouse-east --strategy canary --dry-run
Dry run: Would deploy v2.2.0 to 12 devices in group 'warehouse-east'
Strategy: canary (1 device first, then remaining 11)
Rollback: enabled
rosfit certs
Generate and provision TLS certificates for mTLS authentication.
rosfit certs generate
Generate a new CA and device certificate pair:
rosfit certs generate
| Flag | Default | Description |
|---|---|---|
--output | ./certs | Output directory |
--cn | device ID | Common Name for the certificate |
--days | 365 | Certificate validity in days |
--ca | generate new | Path to existing CA cert for signing |
rosfit certs generate --output /etc/rosfit/certs --cn bot-01 --days 730
rosfit certs provision
Provision a certificate to a device and update its MQTT credentials:
rosfit certs provision dev_k8m2n4
| Flag | Default | Description |
|---|---|---|
--cert | — | Path to device certificate |
--key | — | Path to device private key |
--ca | — | Path to CA certificate |
--deploy | false | Push certs to device over MQTT (requires existing connection) |
rosfit certs provision dev_k8m2n4 --cert ./certs/bot-01.crt --key ./certs/bot-01.key --ca ./certs/ca.crt --deploy