Advanced Flightops workflows

Start with the user guide for the flightops command. This page covers the component commands for recording analysis, project investigation, simulation gates, and evidence review. Each linked guide has the full input format and failure rules for its task.

Component commands

The beta install puts these commands on your PATH next to flightops. Like flightops, they need an activated device.

Command	Use it to
`onscope`	Diagnose a running ROS 2 graph: sourcing, graph snapshots, rates, TF, and `doctor` with 16 detectors.
`splashdown`	Analyze MCAP recordings: stats, bounded queries, slices, assertions, triage, fixtures, replay, and reports.
`lcc` (also `launchcommit`)	Run the local launch gate: init, probe, run, intake, compare, and bench.
`highbay`	Lease warm, isolated colcon workspaces for builds.
`flightops-tui`	Run development subcommands such as `workspace`, `provenance`, `timeline`, `tf-history`, `reproduction`, `launch-resolve`, and `config-diff`.
`flightops-results`	Make a desktop HTML report from saved results, as `flightops results` does.
`flightops-mcp`	Serve four Flightops tools to a coding agent over MCP; see integrations (source repository).

Run any command with --help for its subcommands. Source your ROS underlay and overlay for live observations; Flightops does not install ROS. Some guides use example files under demo/ or scripts under scripts/; those need a source checkout, and the guide says so. Testing lists checks for each command.

Inspect a live graph

With ROS sourced and your nodes running:

bash

onscope sourcing
onscope graph --save before.json
onscope peek /scan -n 3
onscope doctor /scan

Replace /scan with your topic. graph saves one observation. peek prints three bounded messages. doctor reports observed discovery, QoS, clock, and namespace problems without changing the nodes. Save findings with --evidence DIR when you need a reviewable trail. For message-time TF queries and session history, use TF history.

Inspect a recording

Use the recording quickstart for a complete no-ROS example. For your own MCAP:

bash

splashdown stats failed-run.mcap
splashdown triage failed-run.mcap

Choose a bounded window before making a claim about an incident. A query's outcome and complete fields tell you whether it covered the whole requested window. Evidence queries explains timestamp bounds and sample limits. Replay readiness explains how to retain static transforms, warm-up messages, and resource dependencies when slicing.

Turn a failure into a fixture

After triage identifies the input topics, launch entrypoint, and failure window, create a fixture:

bash

splashdown fixture failed-run.mcap \
  --window 8 20 \
  --replay-topics /cmd_vel /tf \
  --entrypoint my_robot:launch/test.launch.py \
  -o replay-fixtures/cmd-vel-dropout
splashdown replay replay-fixtures/cmd-vel-dropout --dry-run --project-dir .

Replace the paths, topics, and times with those from your recording. Review the generated fixture.yaml and assertions before running a real replay. Keep the fixture, sidecar, recording, hashes, and verdict together. The recorded failure guide (source repository) covers fixture authoring and replay.

Run a local quality gate

From the project under test:

bash

lcc init
lcc probe
lcc run

Review .launchcommit.yaml after init, before run. The run prints its output directory under .launchcommit/runs/. Keep verdict.json, logs, and recordings from that directory. A skipped or refused stage is not a pass. For an existing ROS and Gazebo project, use project intake first. For two retained runs, use proof comparison. The simulation experiments guide covers paired revisions, seeds, and fault runs.

Investigate a project

flightops-tui workspace combines source declarations, graph observations, and saved evidence. Use --project for source mapping candidates and --session-dir when you want to reopen the same workspace. The development workspace (source repository) guide shows the command and terminal controls.

Choose the task you need:

Task	Guide
Save project settings and resume a session	Project profiles
Record a hypothesis, run a check, and attach evidence	Development experiments (source repository)
Find parameter origins, inspect timelines, or trace change impact	Investigation workflows
Compare behavior against measured budgets	Behavior and fault workflows
Check lidar, IMU, and other input pipelines	Device integration recipes
Copy and verify an evidence package	Reproduction packages

These tools report observed results and unresolved mappings. Reopening a session does not rerun its checks. A saved package must be explicitly rerun before it can establish a result in another environment.

Optional AI assistance

Use the setup tutorial for a provider connection. Standard startup does not contact a provider. Assistant actions in the terminal require explicit enablement and review. The ChatGPT account route (preview) supports bounded isolated text and attached-evidence explanations after runtime, bubblewrap, sign-in, and connection checks. Native Codex tools stay disabled. API and local model connections have a separate connection test. See testing for current validation limits.

Supported saved-result inputs

flightops results and flightops-results accept supported Flightops JSON records from gates, recording assertions and queries, comparisons, workspace checks, and development experiments. They also accept incident and benchmark records. Each input is limited to 4 MiB; one report accepts up to 100 inputs. Malformed JSON, unsupported schemas, non-finite numbers, and inconsistent pass claims are refused. Use the source JSON when an exact value or complete record matters. Follow review saved results to generate HTML.

Troubleshooting

Start with flightops doctor for installed startup problems. For recording, workspace, and gate errors, use troubleshooting and the guide for the command you ran. To report a problem, write to beta@flightops.dev (see feedback and support). Include the printed error, the command, flightops --version, the result JSON, and the log path.