🛰️ GPS CLI - Universal Device Location Tracker

A powerful command-line tool for tracking device location across multiple platforms. Track your Linux, macOS, Windows, Android, or iOS device with ease using free or self-hosted tracking providers.

🚀 Quick Start: Install in 2 minutes | 🆓 Free Forever | 🌍 Works Everywhere | 🔒 Privacy-Focused

🆓 FREE Default Configuration

Zero configuration required! GPS-CLI works immediately with:

FREE Traccar Demo Server (https://demo2.traccar.org) - NO account or signup needed!
IP-Based Geolocation - NO GPS hardware required (city-level accuracy)
Instant Setup - Just run gps setup and you're tracking in seconds

Perfect for testing, personal use, or getting started quickly. Want more precision or privacy? Easily switch to self-hosted options or GPS hardware later!

✨ Features

🌍 Multi-Provider Support

Traccar (Free demo server + self-hosted)
OwnTracks (Privacy-focused MQTT/HTTP)
PhoneTrack (Nextcloud integration)
GPSLogger (Custom HTTP endpoints)

📡 Flexible Location Sources

IP-based geolocation (works anywhere)
GPS hardware support (via gpsd)
Automatic fallback mechanisms

🗺️ Web-Based Tracking

Real-time map visualization
Shareable tracking URLs
Works on any device with a browser

⚙️ Highly Configurable

Adjustable update intervals
Background tracking daemon
Privacy-focused local storage

🎨 User-Friendly Interface

🎉 NEW: Interactive menu mode (run gps without arguments)
Beautiful color-coded menu with 8 options
Continuous loop - no need to restart between operations
All prompts show default values
Simple command structure for CLI automation
Comprehensive help system

📊 Location History

Track last 50 locations
Timestamped entries
Easy history review

🔒 Privacy & Security

All configuration stored locally
Self-hosted options available
No data sharing required

📋 Requirements

Core Dependencies:

bash (version 4.0+)
curl (for API requests)
jq (for JSON parsing)

Optional:

gpsd and cgps (for GPS hardware support)

Installing Dependencies

Debian/Ubuntu/Kali:

sudo apt-get update
sudo apt-get install -y bash curl jq

# Optional: for GPS hardware
sudo apt-get install -y gpsd gpsd-clients

macOS:

brew install bash curl jq

# Optional: for GPS hardware
brew install gpsd

Arch Linux:

sudo pacman -S bash curl jq gpsd

🚀 Installation

Quick Install

cd /home/kali/labs
git clone https://github.com/yourusername/gps-cli.git
cd gps-cli
./install.sh

Manual Installation

# Make script executable
chmod +x gps

# Create symlink
mkdir -p ~/.local/bin
ln -s $(pwd)/gps ~/.local/bin/gps

# Add to PATH (if not already)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc  # or ~/.bashrc
source ~/.zshrc

Verify Installation

gps help

🎯 Quick Start

Interactive Mode (Recommended for Beginners)

Simply run gps without any arguments to launch the beautiful interactive menu:

gps

You'll see a menu like this:

╔════════════════════════════════════════════════════════════════════════════╗
║           🛰️  GPS CLI - Universal Device Location Tracker v0.3.0         ║
╚════════════════════════════════════════════════════════════════════════════╝

  [1] 🔧 Setup Tracking Provider    - Configure Traccar, OwnTracks, etc.
  [2] ▶️  Start Tracking             - Begin sending location updates
  [3] ⏹️  Stop Tracking              - Stop location updates
  [4] 📊 Show Status                - View tracking status and last location
  [5] 🗺️  Show Tracking URL          - Display web tracking link
  [6] ⚙️  Configure Settings         - Adjust update interval and options
  [7] 📜 View Location History       - Show recent location updates
  [8] 📡 List Providers              - Show available tracking providers

  [0] 🚪 Exit                        - Quit GPS CLI

Features:

🔄 Continuous loop - no need to restart between operations
⌨️ Simple number-based navigation
🎨 Color-coded menu items for easy identification
⚙️ All prompts show default values
⌃C Graceful exit with Ctrl+C

First Time Setup (via Interactive Menu):

Select option [1] to setup tracking provider
Choose Traccar (option 1)
Select FREE demo server (default)
Enter a device name (or press Enter for auto-generated)
Back to main menu - select [2] to start tracking
Select [5] to get your tracking URL
Open the URL in a browser to see your device on the map!

Command-Line Mode (For Automation & Scripts)

Prefer commands? All CLI functionality is still available:

1. Setup Tracking Provider

gps setup

Choose Traccar (option 1), select the FREE demo server, and give your device a name (e.g., "my-laptop" or "gps-tracker")!

The device name will be used to identify your device in the Traccar dashboard.

2. Start Tracking

gps start

3. Get Your Tracking URL

gps url

Open the URL in any web browser to see your device on a map!

4. Check Status

gps status

5. Stop Tracking

gps stop

📖 Usage

Commands

Command	Alias	Description
`gps setup`	-	Configure tracking provider
`gps start`	-	Start GPS tracking
`gps stop`	-	Stop GPS tracking
`gps status`	`s`	Show tracking status and location
`gps url`	`link`	Display tracking URL
`gps config`	`configure`	Configure update interval
`gps history`	`h`	Show location history
`gps providers`	`list`	List available providers
`gps help`	`-h`, `--help`	Show help message

Examples

Start tracking with default settings:

gps start

Check your current status:

gps status

Get tracking URL to share:

gps url

Change update interval to 30 seconds:

gps config
# Enter: 30

View location history:

gps history

List all providers:

gps providers

🛠️ Providers

1. Traccar (Recommended) 🌟

Best for: Everyone - Easiest setup with free demo server

Setup:

Run gps setup
Select option 1 (Traccar)
Select option 1 (Free demo server)
Enter a device name (e.g., "gps-tracker") or press Enter for auto-generated name
Done! Your tracking URL will be displayed

Features:

✅ Free demo server (no registration)
✅ Web-based map interface
✅ Real-time tracking
✅ Custom device names for easy identification
✅ Osmand protocol for better device management
✅ Self-hosted option available

Web Interface:

Demo server: https://demo2.traccar.org
Login not required for viewing
Just use your device ID in the URL

Self-Hosting Traccar:

# Docker installation
docker run -d --name traccar \
  -p 8082:8082 \
  -p 5055:5055 \
  traccar/traccar:latest

Then configure GPS CLI to use http://your-server:8082

2. OwnTracks 🔒

Best for: Privacy-conscious users with technical expertise

Requirements:

MQTT broker (Mosquitto) or HTTP endpoint
Self-hosted OwnTracks Recorder for web interface

Setup:

Install Mosquitto MQTT broker
Install OwnTracks Recorder
Run gps setup and select OwnTracks
Enter your endpoint URL

Installation (Server):

# Install Mosquitto
sudo apt-get install mosquitto mosquitto-clients

# Install OwnTracks Recorder
# See: https://github.com/owntracks/recorder

Features:

✅ End-to-end encryption
✅ Privacy-focused
✅ MQTT or HTTP support
⚠️ Requires own server

3. PhoneTrack ☁️

Best for: Nextcloud users

Requirements:

Nextcloud instance
PhoneTrack app installed

Setup:

Install PhoneTrack on your Nextcloud
Create a tracking session
Get session token from PhoneTrack
Run gps setup and select PhoneTrack
Enter Nextcloud URL and session token

Installation (Nextcloud):

# Install via Nextcloud app store or:
sudo -u www-data php occ app:install phonetrack

Features:

✅ Integrated with Nextcloud
✅ Session-based tracking
✅ Privacy-first design
⚠️ Requires Nextcloud

4. GPSLogger 🔧

Best for: Custom integrations and developers

Requirements:

HTTP endpoint that accepts POST requests

Setup:

Set up your custom endpoint
Run gps setup and select GPSLogger
Enter endpoint URL and auth token

Example Backend (Node.js/Express):

app.post('/gps/update', (req, res) => {
  const { device_id, latitude, longitude, timestamp } = req.body;
  // Store location in your database
  res.json({ success: true });
});

Features:

✅ Maximum flexibility
✅ Custom integrations
✅ Any HTTP endpoint
⚠️ DIY implementation

📱 Mobile Devices

Android

Option 1: Traccar Client (Recommended)

Install "Traccar Client" from Google Play Store
Open app → Settings
Set Device Identifier to your GPS CLI device ID
Set Server Address: https://demo2.traccar.org:5055
Start tracking

Option 2: GPSLogger for Android

Install "GPSLogger" from F-Droid or Google Play
Configure custom URL endpoint
Enable automatic logging

iOS

OwnTracks for iOS

Install "OwnTracks" from App Store
Configure HTTP endpoint or MQTT broker
Set device ID and credentials
Start tracking

Other Options

Traccar Manager - iOS/Android management app
PhoneTrack - Nextcloud mobile app
Any app that can POST to HTTP endpoints

⚙️ Configuration

Config Location

All configuration is stored in ~/.config/gps-cli/:

config.json - Main configuration
history.json - Location history
gps.log - Application logs
.env - Provider credentials (optional)
tracker.pid - Background process ID

Environment Variables

Copy .env.sample to ~/.config/gps-cli/.env for advanced configuration:

cp .env.sample ~/.config/gps-cli/.env
nano ~/.config/gps-cli/.env

Key Settings:

# Update interval (seconds)
UPDATE_INTERVAL=60

# GPS source (auto, ip, hardware)
GPS_SOURCE=auto

# Provider selection
GPS_PROVIDER=traccar

Update Intervals

# Interactive configuration
gps config

# Common intervals:
# 30  = 30 seconds (high frequency)
# 60  = 1 minute (default, balanced)
# 300 = 5 minutes (battery saving)
# 600 = 10 minutes (low frequency)

🔧 Troubleshooting

Tracking Not Starting

Check dependencies:

which curl jq

Check configuration:

cat ~/.config/gps-cli/config.json

Check logs:

tail -f ~/.config/gps-cli/gps.log

Location Not Updating

Verify background process:

gps status

Check IP geolocation APIs:

curl -s https://ipapi.co/json/ | jq

Restart tracking:

gps stop
gps start

Tracking URL Not Working

Traccar demo server:

URL format: https://demo2.traccar.org/?id=YOUR_DEVICE_NAME
Device must send at least one location update first
Wait 1-2 minutes after starting tracking
Device will appear in the dashboard with the name you chose during setup

Self-hosted:

Verify server is accessible
Check firewall rules
Ensure correct port configuration

Permission Denied

Make script executable:

chmod +x ~/.local/bin/gps

Check PATH:

echo $PATH | grep .local/bin

GPS Hardware Not Detected

Install gpsd:

sudo apt-get install gpsd gpsd-clients

Check GPS device:

lsusb  # Look for GPS device
cgps   # Test GPS reception

Start gpsd:

sudo gpsd /dev/ttyUSB0 -F /var/run/gpsd.sock

🔐 Privacy & Security

Data Storage

Local only: All configuration stored in ~/.config/gps-cli/
No cloud sync: Data never leaves your device (unless you configure it)
Open source: Audit the code yourself

IP Geolocation

Approximate: City-level accuracy (5-50km radius)
Third-party APIs: ipapi.co and ip-api.com
Limited data: Only IP address sent to geolocation APIs
Fallback: Multiple providers for reliability

Provider Security

Provider	Privacy Level	Data Storage	Encryption
Traccar (demo)	⚠️ Public	Demo server	HTTPS
Traccar (self-hosted)	✅ Private	Your server	HTTPS
OwnTracks	✅ Private	Your server	End-to-end
PhoneTrack	✅ Private	Your Nextcloud	HTTPS
GPSLogger	🤷 Depends	Your endpoint	Your choice

Recommendations

For maximum privacy: Use self-hosted OwnTracks or Traccar
For testing: Traccar demo is fine (temporary use)
For existing setup: PhoneTrack if you already use Nextcloud
For custom needs: GPSLogger with your own backend

🌐 Cross-Platform Support

Linux ✅

Fully supported
All providers available
GPS hardware support via gpsd

macOS ✅

Fully supported
All providers available
Limited GPS hardware support

Windows (WSL) ✅

Supported via WSL or MSYS2
All providers available
No GPS hardware support

Android 📱

Use Traccar Client app
Configure with same device ID
Points to same tracking URL

iOS 📱

Use OwnTracks app
Requires MQTT/HTTP setup
Alternative: Traccar iOS app

📊 Use Cases

Personal Tracking

Track your laptop when traveling
Find lost devices
Monitor device location history

Asset Tracking

Track company equipment
Monitor fleet vehicles (with GPS hardware)
Logistics and delivery tracking

Development & Testing

Test location-based applications
Simulate device movement
API integration testing

Security & Backup

Emergency location tracking
Anti-theft monitoring
Backup location tracking

🤝 Contributing

Contributions are welcome! Here's how you can help:

Report bugs: Open an issue
Suggest features: Start a discussion
Submit PRs: Fork, code, and create pull request
Improve docs: Fix typos, add examples
Share providers: Add support for new tracking services

📄 License

This project is free and open-source. Use, modify, and distribute as you wish.

🙏 Acknowledgments

Traccar: Excellent open-source GPS tracking platform
OwnTracks: Privacy-focused location tracking
PhoneTrack: Great Nextcloud integration
IP Geolocation APIs: ipapi.co and ip-api.com

📞 Support

Documentation: This README
Issues: GitHub Issues
Discussions: GitHub Discussions
Logs: Check ~/.config/gps-cli/gps.log

🗺️ Roadmap

v0.2.0 (Released)

v0.3.0 (Planned)

v0.4.0 (Future)

📝 Version

Current version: 0.2.0

See CHANGELOG.md for version history.

Made with ❤️ for privacy-conscious device tracking

🛰️ Track responsibly | 🔒 Privacy matters | 🌍 Location everywhere

Name		Name	Last commit message	Last commit date
Latest commit History 17 Commits
.github		.github
.env.sample		.env.sample
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
QUICKSTART.md		QUICKSTART.md
README.md		README.md
demo.sh		demo.sh
gps		gps
install.sh		install.sh

License

alexcolls/gps-cli

Folders and files

Latest commit

History

Repository files navigation

🛰️ GPS CLI - Universal Device Location Tracker

🆓 FREE Default Configuration

✨ Features

📋 Requirements

Installing Dependencies

🚀 Installation

Quick Install

Manual Installation

Verify Installation

🎯 Quick Start

Interactive Mode (Recommended for Beginners)

Command-Line Mode (For Automation & Scripts)

1. Setup Tracking Provider

2. Start Tracking

3. Get Your Tracking URL

4. Check Status

5. Stop Tracking

📖 Usage

Commands

Examples

🛠️ Providers

1. Traccar (Recommended) 🌟

2. OwnTracks 🔒

3. PhoneTrack ☁️

4. GPSLogger 🔧

📱 Mobile Devices

Android

iOS

Other Options

⚙️ Configuration

Config Location

Environment Variables

Update Intervals

🔧 Troubleshooting

Tracking Not Starting

Location Not Updating

Tracking URL Not Working

Permission Denied

GPS Hardware Not Detected

🔐 Privacy & Security

Data Storage

IP Geolocation

Provider Security

Recommendations

🌐 Cross-Platform Support

Linux ✅

macOS ✅

Windows (WSL) ✅

Android 📱

iOS 📱

📊 Use Cases

Personal Tracking

Asset Tracking

Development & Testing

Security & Backup

🤝 Contributing

📄 License

🙏 Acknowledgments

📞 Support

🗺️ Roadmap

v0.2.0 (Released)

v0.3.0 (Planned)

v0.4.0 (Future)

📝 Version

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages