English | 简体中文
Headless, agent-first MAVLink ground-control CLI for ArduPilot vehicles.
Quick start — paste this into any coding agent:
uv tool install mavctl
npx skills add LeaderOnePro/mavctl -y -gConnected to a flight controller and you can tell your Agent what to do in plain language — take off, hover, land, RTL, one instruction at a time.
mavctl is ArduPilot-first and built to be driven by both humans on a terminal and AI coding agents (Claude Code, Codex, OpenClaw, …). A resident daemon keeps the MAVLink link alive and caches vehicle state; every CLI call is one short, structured request to that daemon.
Status: developed and verified against ArduPilot SITL. It has not been proven across the breadth of real MAVLink vehicles and is not presented as ready for production flight on a real aircraft.
GUI ground stations such as Mission Planner or QGroundControl are excellent for a human at the controls — and a poor interface for a shell script or an LLM agent: clickable UIs, no stable exit codes, no machine-readable output.
mavctl takes the other side of that trade:
- the daemon owns the MAVLink connection and continuously caches telemetry, so each command is quick and stateless;
- every command prints human-readable output by default and structured JSON
with
--json; - failures carry explicit exit codes (3 daemon down, 4 link lost, 5 guard rejection, 6 vehicle NACK / timeout) instead of stack traces;
- dangerous operations pass safety guards before anything reaches the vehicle;
- mavctl embeds no LLM — it is designed to be called by agents such as Claude Code, Codex or OpenClaw, or by plain bash.
Implemented commands — this is the complete list:
mavctl daemon start|stop|status
mavctl status
mavctl telemetry
mavctl arm
mavctl disarm
mavctl mode <MODE>
mavctl takeoff --alt <metres>
mavctl land
mavctl rtl
mavctl mission upload <mission.json> --confirm [--dry-run]
mavctl mission download [--output <mission.json>] [--json]
mavctl mission clear --confirm [--dry-run]
mavctl mission start --confirm [--wait] [--timeout] # 0.4.0; mock- and ArduCopter SITL-validated
mavctl operation get <operation_id> [--json]Cross-cutting behaviour:
| Flag / behaviour | Meaning |
|---|---|
--json |
structured output on stdout; errors as {"error": {...}} on stderr |
--confirm |
required on every state-changing command; without it exit code 5 |
--dry-run |
run the exact same guards, never reach the vehicle |
--wait --timeout <s> |
block until the target state is reached (default 60 s) |
| idempotent repeats | re-applying an achieved change succeeds ("already armed") |
| transaction safety | ACK/NACK handling, serialized commands, link-loss abort |
Mission upload/download/clear are validated against ArduPilot SITL
(lossless upload → download round-trip, including takeoff items): the
automated suite runs on a dedicated MAVProxy-free loopback instance, and the
shared sim_vehicle + MAVProxy relay topology was validated with the same
suite plus a manual CLI acceptance. mavctl uses its own GCS identity
(default source system 254, configurable via
mavctl daemon start --source-system <1..255>) so it never shares an
on-wire identity with the GCS it was validated against (MAVProxy 1.8.74,
default 255/230); transfers additionally converge on duplicated relay
traffic. Mission support is ArduPilot SITL validated only — no
real-aircraft claim. The SITL conformance ran against a locally modified
ArduPilot checkout at revision 4c98c9221a; the only reviewed source
modification was a macOS host-build/linker workaround in AP_FWVersion.h
that does not alter mission/GCS runtime code.
Mission start (0.4.0, mock- and ArduCopter-SITL-validated):
mavctl mission start --confirm arms nothing and takes off nothing — it
sends MAV_CMD_MISSION_START to a vehicle that already has a verified
stored mission, an armed heartbeat, and a fresh link. On ArduCopter the
vehicle handler may transition to AUTO and start or resume execution —
explicit, confirmation-gated behavior. --wait observes the bounded start
milestone (mission ACTIVE + mode AUTO), never whole-mission completion.
SITL execution conformance passed against an isolated no-MAVProxy loopback
ArduCopter instance (automated in tests/test_mission_execution_sitl.py:
guard negative paths, the start milestone, idempotent re-start, RTL
supersession); no real-aircraft claim.
Health observation (0.4.1, observe-only; ArduCopter SITL-validated):
status --json carries a health block with raw vehicle-reported
observations — the estimator (EKF_STATUS_REPORT: raw flag mask, dialect
flag names, variance floats, independent monotonic age), raw SYS_STATUS
sensor present/enabled/health bitmasks, and the most recent
PreArm:/Arm:/PreArm_EKF: diagnostic from STATUSTEXT. It is strictly
observe-only: no health CLI command, no health/pre-arm guard, and
MAV_CMD_RUN_PREARM_CHECKS is never sent. estimator.status is
unknown or observed — it never claims healthy; unknown (never
received or stale) is not a health judgement, and a stale cached
observation is history, not permission. ArduPilot's own pre-arm checks
remain the final authority. Automated in tests/test_health_observation.py
(mock) and tests/test_health_sitl.py (live loopback observation).
Not implemented — current scope only, not a roadmap promise:
Mission pause/resume/stop/set-current (mission start ships mock- and
ArduCopter-SITL-validated in 0.4.0)
Operation cancel
Parameters
Geofence
Log download / analysis
Firmware flashing
Multi-vehicle orchestration
Notable in 0.4.1:
- Health observation runtime v1 (observe-only):
status --jsongains ahealthblock — rawEKF_STATUS_REPORTobservation (flag mask, dialect-known flag names, variance fields, independent monotonic age), rawSYS_STATUSsensor present/enabled/health bitmasks, and the most recent locked-autopilotPreArm:/Arm:/PreArm_EKF:STATUSTEXT diagnostic with its own freshness age. Strictly observe-only: no health CLI command, no health advisory or hard guard,MAV_CMD_RUN_PREARM_CHECKSis never sent,unknown/stale is never healthy, and ArduPilot's pre-arm checks remain the final authority.
Notable in 0.4.0:
- Operation foundation (Phase 3B-0):
takeoff --wait,land --waitandrtl --waitrun their milestone observation through a daemon-owned operation: the command lock is released as soon as the vehicle accepts the command, sortl/land/statusstay available while a wait is in progress. - A later accepted command supersedes an in-flight wait: the superseded
command reports exit 6
operation_superseded— it was executed (ACKed), not cancelled; re-check the vehicle withmavctl status. --timeoutexpiry reports exit 6operation_wait_timeoutwithoperation_still_running: true— the accepted vehicle action is not cancelled by the client timeout.mavctl operation get <id>observes an operation (read-only). If the daemon restarted, the operation is unknown — re-checkmavctl status; that does not mean the vehicle action did not happen.- Mission start (Phase 3B-1):
mavctl mission start --confirm [--wait] [--timeout]— explicit, confirmation-gated execution. On ArduCopter it may transition the vehicle to AUTO and start/resume the stored mission; it never motor-arms or takes off implicitly, and--waitobserves the bounded startup milestone (mission ACTIVE + mode AUTO), never whole-mission completion. - Guard semantics fix found by SITL conformance: an empty ArduPilot
mission answers
MISSION_COUNT == 1(the vehicle-managed home slot is re-written on every unlocked arming), so the mission-start guard requires wire count >= 2.
Notable in 0.3.0:
- Mission Protocol Core (Phase 3A):
mavctl mission upload / download / clear— ArduPilot-first Mission JSON v1 (takeoff/waypoint/land/rtl), lossless-or-fail download, fresh-ground guards, clear verified by count read-back. - ArduPilot compatibility: home-slot wire convention, float
MISSION_REQUESTupload pacing, relay-residue settle quarantine on the validated shared MAVProxy topology. - Distinct mavctl GCS identity (default source system 254, component 190;
mavctl daemon start --source-system <1..255>) so mavctl coexists with a conventional GCS on 255. - Mission support is ArduPilot SITL validated only — no real-aircraft claim; mission execution / start / AUTO was intentionally not included in 0.3.0 (mission start shipped in 0.4.0).
Notable in 0.2.1:
mavctl --versionprints the installed version — no daemon or vehicle needed.status --jsoncarries per-stream freshness ages:telemetry_age_s,gps_age_s,battery_age_s,home_position_age_s,landed_state_age_s(monotonic-clock based; they keep counting after heartbeat loss so cache staleness stays visible).- Ordinary non-force
disarmrequires fresh positive ground evidence; stale apparent ground evidence is rejected asground_state_stale(exit 5).
Requires Python >= 3.10 and uv. Always bring up SITL first; do not point an agent-driven workflow at a real vehicle.
Terminal 1 — start ArduPilot SITL:
sim_vehicle.py -v ArduCopter --out udp:127.0.0.1:14550Terminal 2 — install from source and connect:
uv sync
uv run mavctl daemon start --connect udp:127.0.0.1:14550
uv run mavctl status --jsonSafe takeoff to 10 m and return to launch:
uv run mavctl mode GUIDED --confirm --wait
uv run mavctl arm --confirm
# Poll status --json until armed=true (the arm ACK can beat the heartbeat)
uv run mavctl takeoff --alt 10 --confirm --wait --timeout 45
uv run mavctl rtl --confirm --wait --timeout 120
uv run mavctl daemon stopSafety notes — read before pointing mavctl at anything that flies:
- Validate every workflow in SITL first; treat real-aircraft use as its own review process.
- After
arm, pollstatus --jsonuntilarmed=truebefore takeoff: the COMMAND_ACK can arrive about one heartbeat before reported state catches up. - End flights with
rtl/land, notdisarm. Ordinarydisarmrequires provable ground contact (ground_state_unknownotherwise). disarm --forceis an emergency motor stop only — in flight it can cause a crash.- There is no
arm --forceanywhere in mavctl; pre-arm checks cannot be bypassed.
mavctl 0.4.0 is published on production PyPI. Install with:
uv tool install --upgrade mavctl
# or run once without a persistent install:
uvx mavctl --help
# or:
pipx install mavctlVerify the install — mavctl --version needs no daemon or vehicle:
mavctl --versionBefore pointing mavctl at anything that flies, walk through the SITL-first quickstart above. Release history and the publishing runbook live in docs/PUBLISHING.md.
For development from source, use uv sync and uv run mavctl …:
git clone https://github.com/LeaderOnePro/mavctl.git
cd mavctl
uv sync
uv run mavctl --helpmavctl bundles a portable Agent Skill under skills/mavctl-flight/
(entrypoint plus workflows / safety / troubleshooting references). It is a
source asset of this repo: installing the Skill is independent of installing
the mavctl CLI from PyPI, e.g. uv tool install mavctl.
Install the bundled Agent Skill globally:
npx skills add LeaderOnePro/mavctl -y -gThe community skills CLI manages installation for the agent runtimes it supports, according to its current environment and configuration. See docs/SKILLS_CLI_ACCEPTANCE.md for tested behaviour and compatibility notes.
Short version; full details in skills/mavctl-flight/references/safety.md:
- the daemon owns the vehicle link; CLI calls are short transactions;
- state-changing commands require
--confirm;--dry-runpreviews decisions; - exit 4 = no live vehicle state (link lost / heartbeat expired), including
mid-
--waitloss (link_lost_during_wait); - exit 5 = guard rejection with structured
reason+hint; - exit 6 = vehicle NACK / ACK timeout / wait timeout;
- force-arm does not exist at any layer (CLI option, RPC field, adapter verb);
- ordinary
disarmneeds positive ground evidence, elseground_state_unknown(exit 5); - after link loss,
statusreflects stale cache:armedrenders unknown/n/a, never silently disarmed.
uv sync
uv run ruff check .
uv run mypy .
uv run pytest -m "not sitl"
uv run pytest -m sitl # requires a running ArduPilot SITLFurther reading:
- docs/SITL_ACCEPTANCE.md
- docs/SITL_ACCEPTANCE_PHASE2.md
- AGENTS.md — architecture rules and contribution constraints
- skills/mavctl-flight/SKILL.md — agent-facing flight guidance
MIT — Copyright (c) 2026 LeaderOnePro.