CLI
The Foxglove CLI helps you upload, export, and manage your data from the command line.
These examples use CLI v2. For changes from v1, see the v2 migration guide and v2.0.0 release notes.
Installation
Download the latest release from your command line.
| OS | architecture | command |
|---|---|---|
| linux | ||
| amd64 | curl -fL https://github.com/foxglove/foxglove-cli/releases/latest/download/foxglove-linux-amd64 -o foxglove && chmod +x foxglove | |
| arm64 | curl -fL https://github.com/foxglove/foxglove-cli/releases/latest/download/foxglove-linux-arm64 -o foxglove && chmod +x foxglove | |
| macos | ||
| any | Using homebrew: brew install foxglove-cli | |
| amd64 | curl -fL https://github.com/foxglove/foxglove-cli/releases/latest/download/foxglove-macos-amd64 -o foxglove && chmod +x foxglove | |
| arm64 | curl -fL https://github.com/foxglove/foxglove-cli/releases/latest/download/foxglove-macos-arm64 -o foxglove && chmod +x foxglove | |
| windows | ||
| amd64 | curl.exe -fL https://github.com/foxglove/foxglove-cli/releases/latest/download/foxglove-windows-amd64.exe -o foxglove.exe | |
| arm64 | curl.exe -fL https://github.com/foxglove/foxglove-cli/releases/latest/download/foxglove-windows-arm64.exe -o foxglove.exe |
The download is saved in your current folder. On macOS/Linux, run ./foxglove --help to try it, or install it in your system's PATH:
sudo mkdir -p /usr/local/bin
sudo install -m 755 ./foxglove /usr/local/bin/foxglove
foxglove version
On Windows, run .\foxglove.exe --help in PowerShell, or move foxglove.exe to a folder on your Path.
To install a specific release, see the releases page.
Getting started
Before interacting with your data, you must first authenticate with your Foxglove account:
foxglove auth login
Alternatively, configure an API key:
foxglove auth configure-api-key
Project defaults
Commands that support a project select it in this order: --project-id, FOXGLOVE_DEFAULT_PROJECT_ID, then the saved default:
foxglove config set project-id prj_abcd1234
Command help
For a list of all available CLI commands:
foxglove -h
Enable shell autocompletion for subcommands and parameters. Choose your shell and add the command to its startup file to enable completion in future sessions:
- Bash
- Zsh
- Fish
- PowerShell
source <(foxglove completion bash)
autoload -Uz compinit && compinit
source <(foxglove completion zsh)
foxglove completion fish | source
foxglove completion powershell | Out-String | Invoke-Expression
Actions
| Create | List | Delete | |
|---|---|---|---|
| Projects | foxglove projects list | ||
| Devices | foxglove devices add --name "my device" --project-id prj_abcd1234 | foxglove devices list | |
| Recordings | foxglove upload ~/data/bags/gps.bag --device-id dev_drpLqjBZYUzus3gv | foxglove recordings list | foxglove recordings delete rec_123 |
| Sessions | foxglove sessions add --device-id dev_drpLqjBZYUzus3gv --key run-001 | foxglove sessions list | foxglove sessions delete rs_123 |
| Datasets | foxglove datasets add --name "Night drives" --project-id prj_abcd1234 | foxglove datasets list | foxglove datasets delete dset_123 |
| Episodes | foxglove episodes add --recording-id rec_123 --project-id prj_abcd1234 | foxglove episodes list | foxglove episodes delete ep_123 |
| Events | foxglove events add --device-id dev_flm75pLkfzUBX2DH --start 2022-01-01T12:00:00Z --end 2022-01-01T12:00:00Z --metadata 'someKey:someValue' | foxglove events list | |
| Extensions | foxglove extensions publish ./my-extension.1.0.0.foxe | foxglove extensions list | foxglove extensions unpublish ext_BsGXKGsZ9c4WQF1 |
Uploads and exports
Upload a local MCAP or ROS 1 bag file:
foxglove upload recording.mcap --device-id dev_drpLqjBZYUzus3gv
The CLI reports the upload request ID on stderr. Importing continues in the background; use that ID to check progress:
foxglove pending-imports list --request-id REQUEST_ID
Associate an upload with a session using --session-id or --session-key. These flags cannot be combined, and --session-key doesn't require a project.
Export by recording, session, episode, or device and time range:
foxglove export --recording-id rec_123 --output-file recording.mcap
foxglove export --session-id rs_123 --output-file session.mcap
foxglove export --episode-id ep_123 --output-file episode.mcap
foxglove export --device-id dev_drpLqjBZYUzus3gv \
--start 2026-10-01T00:00:00Z --end 2026-10-01T01:00:00Z \
--topics /gps/fix,/gps/fix_velocity --output-file output.mcap
Give --start and --end together. The default output format is mcap; use --output-format bag1 for ROS 1 bags or --output-format json for JSON messages from ROS 1 or Protobuf schemas. JSON writes to stdout unless you specify --output-file.
Use --output-file for file downloads so the CLI can recover interrupted MCAP and ROS 1 bag transfers and replace the destination only after the download succeeds. Redirecting stdout to a file doesn't provide the same recovery. Existing destination files are preserved if a download fails.
Sessions and device properties
Set or remove a session key:
foxglove sessions edit rs_123 --key run-002
foxglove sessions edit rs_123 --remove-key
Update device properties without renaming the device. Repeat a multi-select property's key to set its full list of values:
foxglove devices edit dev_drpLqjBZYUzus3gv --property version:65
foxglove devices edit dev_drpLqjBZYUzus3gv --property capabilities:camera --property capabilities:lidar
The property definitions must already exist in your organization. To delete a device, use the Devices page in the app.
Datasets and episodes
Datasets are versioned collections of episodes. An episode is a time range over one or more recordings. These commands require a plan that supports datasets.
Create an episode, add it to a dataset, and commit the draft as a version:
foxglove episodes add --recording-id rec_123 --project-id prj_abcd1234 \
--start 2026-10-01T00:00:00Z --end 2026-10-01T00:00:30Z
# Use the episode ID returned above
foxglove datasets add --name "Night drives" --project-id prj_abcd1234 --episode-id ep_123
# Use the dataset ID returned above
foxglove datasets episodes add dset_123 ep_456
foxglove datasets episodes list dset_123 --version draft
foxglove datasets commit dset_123
Adding or removing episodes changes the draft. Commit it to create a version, or use foxglove datasets discard dset_123 to discard pending changes. Compare versions or restore a committed version into the draft:
foxglove datasets versions list dset_123
foxglove datasets versions compare dset_123 1 2
foxglove datasets versions restore dset_123 1
Download a committed version as one MCAP file per episode plus manifest.json:
foxglove datasets download dset_123 --version 2 --output ./night-drives-v2
The manifest records downloaded, skipped, and failed episodes. Episodes with no available recording data are skipped. Use --strict to also fail when an episode is skipped or downloaded with missing recordings.
Lists and scripting
List commands that accept --limit return 50 results by default. Set --limit to a value from 1 to 2000 to change the page size. When more results may exist, the CLI prints a pagination hint on stderr.
Use --format json or --format csv for scripts. JSON list output wraps results in a data array:
foxglove devices list --format json | jq '.data[]'
foxglove devices list --limit 100 --offset 100 --format csv
Dataset, dataset episode, dataset version, and episode lists, plus dataset version comparisons, use cursor pagination. Read nextCursor from JSON output and pass it to --cursor for the next page. Other commands that accept --limit use --offset.
Use --debug to print HTTP request diagnostics to stderr when troubleshooting failures. See the migration guide for other output and scripting changes.
Visualizing data
The Foxglove CLI tool cannot directly open data in the Foxglove app, but the app binary can accept data source parameters when opened via the command line.