CGPS(1)

🛰️ ✨ CGPS(1) ✨ — the GPSD manual, but make it cute

okay bestie, welcome to cgps, the curses terminal client for gpsd 💖 it's a page in the GPSD Documentation and honestly? she's iconic.

---

🌸 SYNOPSIS 🌸

cgps [OPTIONS] [server[:port[:device]]]

cgps -h

cgps -V

like, that's the whole vibe check right there 🫶

---

💫 DESCRIPTION 💫

cgps is an ncurses based gpsd client. she can run on a serial terminal or a terminal emulator — yes, even the crusty one, she doesn't care 💅 she resembles xgps(1), but without the pictorial satellite display and she does not require X or any other windowing system. no GUI drama, periodt.

cgps does not require root privileges. she'll also run just fine as root. but — and this is the part where you listen to me — running under sudo will cause loss of functionality. so like, don't do that. it's giving self-sabotage 😭

🚨 real talk: none of the error estimates that gpsd provides and cgps displays should be taken as anything other than "goodness" levels. GNSS receiver manufacturers often do not document the basis for their estimates, and the ones who do document them are inconsistent about what they mean. so bestie, take those numbers as a vibe, not a promise 💀

---

🎀 OPTIONS 🎀

• -?, -h, --help — prints a summary of options and then dips out. bye ✨
• -D LVL, --debug LVL — sets the debug level. this one is primarily for use by GPSD developers ngl, and it enables various progress messages to standard error. 🐛
• -i, --imu — show IMU instead of fix and satellite data. ✨
• -l FMT, --llfmt FMT — sets the format of latitude and longitude reports:
  • the value 'd' produces decimal degrees and is the default.
  • the value 'm' produces degrees and decimal minutes.
  • the value 's' produces degrees, minutes, and decimal seconds.
• -m, --magtrack — display tracks as magnetic, not true. 🧲
• -m, --magtrack — display your magnetic track (as opposed to your true track). this is a calculated value, not a measured value. magnetic variation is always potentially subject to large errors, but is usually better than two degrees. (yes, the original page lists -m, --magtrack twice. she contains multitudes 💅)
• -s, --silent — prevents cgps from displaying the raw data coming from the daemon. this display can also be toggled with the s command. 🤫
• -u UNITS, --units UNITS — set the system units for display. follow the keyword with:
  • 'i' for 'imperial' for American units (International Feet in altitude and error estimates, miles per hour in speeds)
  • 'n' for 'nautical' (feet in altitude and error estimates, knots in speed)
  • 'm' for 'metric' (meters in altitude and error estimates, kilometers per hour in speeds)

📝 Note: The USA Survey Foot is not supported. sorry to that foot specifically.

• -V, --version — print the package version and exit. 🏷️

---

🦋 ARGUMENTS 🦋

by default, clients collect data from the local gpsd daemon running on localhost, using the default GPSD port 2947. the optional argument to any client may override this behavior:

[server[:port[:device]]]

for further explanation, and examples, see the ARGUMENTS section in the gps(1) man page 🫶

---

👑 COMMANDS 👑

cgps terminates when you send it a SIGHUP or SIGINT; given default terminal settings this will happen when you type Ctrl-C at it. 👋

cgps will accept a few single letter commands while running:

• c — clear the bottom window.
• d — show lat/lon dd.dddddddd, dd mm.mmmmmm and dd mm ss.ssss
• h — popup a help window.
• i — use imperial units.
• m — use metric units.
• n — use nautical units.
• q — clear screen and exit
• s — toggle showing raw JSON data in the bottom window.
• t — toggle true/magnetic track.

---

🌈 ENVIRONMENT 🌈

the environment variable GPSD_UNITS is checked if no unit system is specified on the command line. it may be set to 'i'. 'imperial', 'm', 'metric', or 'n', 'nautical'.

LC_MEASUREMENT and then LANG are checked if no unit system has been specified on the command line, or in GPSD_UNITS. if the value is 'C', 'POSIX', or begins with 'en_US' the unit system is set to imperial. the default if no system has been selected defaults to metric. 🌍

---

💜 RETURN VALUES 💜

• 0 — on success. slay 🎉
• 1 — on failure
• 2 — failure: terminal too small 😭 (expand the window bestie)

---

⭐ SEE ALSO ⭐

gegps(1), gpsctl(1), gps(1), gpsprof*(1), gpsfake(1), gpscat(1), gpspipe(1), xgps(1). xgpsspeed(1)

libgps(3), libgpsmm(3)

gpsd(8)

---

🧚 RESOURCES 🧚

Project web site: https://gpsd.io/ 🔗

---

💖 COPYING 💖

This file is Copyright 2013 by the GPSD project

SPDX-License-Identifier: BSD-2-clause

---

🎀 and that's the whole page, bestie! GPSD Version 3.27.5, dated 2025-11-04 — go forth and read your satellites, you absolute main character 👑✨💅