CLI Reference

The ados command is the primary way to interact with the agent from the terminal. It is built with Click and communicates with the running agent via its REST API on port 8080.

Global behavior

When you run ados without a subcommand, it displays a rich help screen with all available commands grouped by category. The CLI reads the API key from /etc/ados/pairing.json automatically and sends it as an X-ADOS-Key header on every request to the local API. If the agent is not running, most commands will print an error and suggest starting it with ados start or ados demo.

Info commands

`ados version`

Print the installed agent version.

$ ados version
ados-drone-agent v0.5.3

`ados status`

Show the agent’s current state, including board detection, FC connection, and uptime.

$ ados status
Version:    0.5.3
Uptime:     3847s
Board:      Radxa ROCK 5C Lite (RK3582)
Tier:       4
FC:         True
FC Port:    /dev/ttyS0

Use --json for machine-readable output:

$ ados status --json
{
  "version": "0.5.3",
  "uptime_seconds": 3847,
  "board": {"name": "Radxa ROCK 5C Lite (RK3582)", "tier": 4},
  "fc_connected": true,
  "fc_port": "/dev/ttyS0"
}

`ados health`

Show system resource usage: CPU, memory, disk, and temperature.

$ ados health
CPU:    12.3%
Memory: 34.2%
Disk:   41.8%
Temp:   52.3C

`ados help`

Display the rich CLI cheatsheet with all commands, grouped and color-coded.

`ados diag`

Run a full system diagnostics dump. Prints board info, OS details, network interfaces, systemd service states, FC connection, disk usage, RAM, CPU, temperature, agent config, and installed dependency versions.

$ ados diag
========================================
  Board
========================================
  Name:          Radxa ROCK 5C Lite (RK3582)
  Model:         Radxa ROCK 5C
  Tier:          4
  RAM (total):   16384 MB
  CPU cores:     6
  Architecture:  aarch64

========================================
  System
========================================
  OS:            Linux 6.1.84-6-rk2410
  Distro:        Debian GNU/Linux 12 (bookworm)
  ...

This is the best command to run first when debugging any issue. It covers every subsystem in one output.

Config commands

`ados config`

Print the full configuration as JSON.

$ ados config
{
  "agent": {"device_id": "a1b2c3d4", "name": "my-drone", "tier": "auto", "profile": "auto"},
  "mavlink": {"serial_port": "", "baud_rate": 57600, ...},
  ...
}

`ados config <key>`

Get a specific value using dot-path notation.

$ ados config mavlink.baud_rate
57600

$ ados config video.camera.codec
h264

`ados set <key> <value>`

Set a config value at runtime.

$ ados set mavlink.baud_rate 115200
Set mavlink.baud_rate = 115200

Flight commands

`ados mavlink`

Show the MAVLink/flight controller connection status.

$ ados mavlink
Connected: True
Port:      /dev/ttyS0
Baud:      57600

`ados video`

Show the video pipeline status, including detected cameras, MediaMTX state, and recording status.

$ ados video
State:     streaming
Cameras:   1
  - USB Camera (usb)
Recording: False
MediaMTX:  running

`ados snap`

Capture a JPEG snapshot from the video pipeline and save it to disk.

$ ados snap
Snapshot saved: /var/ados/recordings/snap-2026-04-16T14-30-00.jpg

`ados link`

Show WFB-ng video link statistics: signal strength, SNR, packet counts, FEC recovery, and bitrate.

$ ados link
State:    active
RSSI:     -42 dBm
SNR:      28.5 dB
Channel:  149
Packets:  184523 rx, 12 lost
FEC:      8 recovered, 0 failed
Bitrate:  4200 kbps

Scripting commands

`ados scripts`

List running scripts and their state.

$ ados scripts
  [running] abc123: follow_me.py
  [paused]  def456: survey_grid.py

`ados run <path>`

Start a Python script on the agent.

$ ados run /var/ados/scripts/my_mission.py
Started: abc123

`ados send <command>`

Send a text command to the scripting engine (Tello-style commands like takeoff, land, forward 100).

$ ados send "takeoff"
ok

$ ados send "forward 200"
ok

OTA commands

`ados update`

Show OTA update status: current version, channel, last check time, and any pending update.

$ ados update
Version:    0.5.3
State:      idle
Channel:    stable
Repo:       altnautica/ADOSDroneAgent
Last check: 2026-04-16T10:00:00

`ados check`

Check for available updates from GitHub releases.

$ ados check
Update available: v0.5.4
Changelog: Fixed video pipeline restart on camera hot-plug...

`ados upgrade`

One-step check, download, install, and restart. Prompts for confirmation unless -y is passed.

$ ados upgrade
Checking for updates...
Update available: v0.5.4
Install v0.5.4? [y/N]: y
Downloading and installing...
Installed v0.5.4
Restarting service...
Done.

`ados rollback [version]`

Roll back to a previous version. Without a version argument, rolls back to the version that was running before the last upgrade.

$ ados rollback
Rollback complete. Reverted to v0.5.2.

$ ados rollback 0.5.0
Rollback complete. Reverted to v0.5.0.

Pairing commands

`ados pair`

Show pairing status. If unpaired, displays the pairing code to enter in ADOS Mission Control.

$ ados pair
Paired:     False
Device ID:  a1b2c3d4
Name:       my-drone
Board:      Radxa ROCK 5C Lite (RK3582)
mDNS:       my-drone.local

  +--------+
  | AB12CD |
  +--------+

Enter this code in ADOS Mission Control to pair.

`ados unpair`

Unpair the agent and generate a new pairing code. Requires confirmation.

$ ados unpair
This will unpair the agent. Continue? [y/N]: y
Agent unpaired successfully.
New pairing code: XY34ZW

Tool commands

`ados tui`

Launch the TUI dashboard (requires Textual). See TUI Dashboard for details.

`ados start`

Start the agent in the foreground. Used by systemd service files. For interactive use, prefer ados demo.

`ados demo`

Start in demo mode with simulated telemetry. Useful for testing the GCS, REST API, and TUI without hardware.

$ ados demo --port 8080

`ados uninstall`

Remove the agent from the system. On Linux, stops services, removes /opt/ados/ and /var/ados/, keeps config by default. On macOS, detects pip/pipx/uv and runs the matching uninstall.

# Keep config
$ ados uninstall

# Remove everything
$ ados uninstall --purge

# Skip confirmation
$ ados uninstall -y

`ados logs`

Show agent logs. Wraps journalctl on Linux, reads log files on macOS.

# Last 50 lines
$ ados logs

# Last 200 lines
$ ados logs -n 200

# Follow live
$ ados logs -f

# Since a specific time
$ ados logs --since "1h ago"

Ground station commands

`ados gs`

A subcommand group for ground-station-specific operations. Only relevant when the agent is running in ground station profile.

$ ados gs status
$ ados gs pair
$ ados gs network

See Setup Webapp for more on ground station configuration.

Getting Started

Using the Agent

Core Systems

Scripting

ROS 2 Integration

Operations

​CLI Reference

​Global behavior

​Info commands

​ados version

​ados status

​ados health

​ados help

​ados diag

​Config commands

​ados config

​ados config <key>

​ados set <key> <value>

​Flight commands

​ados mavlink

​ados video

​ados snap

​ados link

​Scripting commands

​ados scripts

​ados run <path>

​ados send <command>

​OTA commands

​ados update

​ados check

​ados upgrade

​ados rollback [version]

​Pairing commands

​ados pair

​ados unpair

​Tool commands

​ados tui

​ados start

​ados demo

​ados uninstall

​ados logs

​Ground station commands

​ados gs