{"id":31558033,"url":"https://github.com/alexcolls/gps-cli","last_synced_at":"2026-04-09T01:31:49.020Z","repository":{"id":317636043,"uuid":"1068186518","full_name":"alexcolls/gps-cli","owner":"alexcolls","description":"🛰️ Universal Device Location Tracker - Track Linux, macOS, Windows, Android, iOS devices with multi-provider GPS support (Traccar, OwnTracks, PhoneTrack, GPSLogger)","archived":false,"fork":false,"pushed_at":"2025-11-25T21:02:47.000Z","size":17,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-29T02:12:32.398Z","etag":null,"topics":["android","bash","cli","cross-platform","device-tracking","geolocation","gps","gps-tracker","ios","linux","location","macos","owntracks","phonetrack","privacy","traccar","tracking"],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alexcolls.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-02T01:38:25.000Z","updated_at":"2025-11-25T21:02:51.000Z","dependencies_parsed_at":"2025-11-28T11:12:06.719Z","dependency_job_id":null,"html_url":"https://github.com/alexcolls/gps-cli","commit_stats":null,"previous_names":["alexcolls/gps-cli"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/alexcolls/gps-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexcolls%2Fgps-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexcolls%2Fgps-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexcolls%2Fgps-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexcolls%2Fgps-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alexcolls","download_url":"https://codeload.github.com/alexcolls/gps-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexcolls%2Fgps-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31581864,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"ssl_error","status_checked_at":"2026-04-08T14:31:17.202Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","bash","cli","cross-platform","device-tracking","geolocation","gps","gps-tracker","ios","linux","location","macos","owntracks","phonetrack","privacy","traccar","tracking"],"created_at":"2025-10-05T00:11:53.151Z","updated_at":"2026-04-09T01:31:48.997Z","avatar_url":"https://github.com/alexcolls.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🛰️ GPS CLI - Universal Device Location Tracker\n\n[![Release](https://img.shields.io/github/v/release/alexcolls/gps-cli?style=flat-square)](https://github.com/alexcolls/gps-cli/releases)\n[![License](https://img.shields.io/github/license/alexcolls/gps-cli?style=flat-square)](LICENSE)\n[![Platform](https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20Windows-blue?style=flat-square)](README.md)\n[![Shell](https://img.shields.io/badge/shell-bash%204.0%2B-green?style=flat-square)](README.md)\n[![CI](https://img.shields.io/github/actions/workflow/status/alexcolls/gps-cli/test.yml?branch=main\u0026style=flat-square\u0026label=tests)](https://github.com/alexcolls/gps-cli/actions)\n[![Issues](https://img.shields.io/github/issues/alexcolls/gps-cli?style=flat-square)](https://github.com/alexcolls/gps-cli/issues)\n[![Stars](https://img.shields.io/github/stars/alexcolls/gps-cli?style=flat-square)](https://github.com/alexcolls/gps-cli/stargazers)\n\nA 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.\n\n\u003e 🚀 **Quick Start:** Install in 2 minutes | 🆓 **Free Forever** | 🌍 **Works Everywhere** | 🔒 **Privacy-Focused**\n\n## ✨ Features\n\n🌍 **Multi-Provider Support**\n- Traccar (Free demo server + self-hosted)\n- OwnTracks (Privacy-focused MQTT/HTTP)\n- PhoneTrack (Nextcloud integration)\n- GPSLogger (Custom HTTP endpoints)\n\n📡 **Flexible Location Sources**\n- IP-based geolocation (works anywhere)\n- GPS hardware support (via gpsd)\n- Automatic fallback mechanisms\n\n🗺️ **Web-Based Tracking**\n- Real-time map visualization\n- Shareable tracking URLs\n- Works on any device with a browser\n\n⚙️ **Highly Configurable**\n- Adjustable update intervals\n- Background tracking daemon\n- Privacy-focused local storage\n\n🎨 **User-Friendly Interface**\n- Colorful CLI output with emojis\n- Simple command structure\n- Comprehensive help system\n\n📊 **Location History**\n- Track last 50 locations\n- Timestamped entries\n- Easy history review\n\n🔒 **Privacy \u0026 Security**\n- All configuration stored locally\n- Self-hosted options available\n- No data sharing required\n\n## 📋 Requirements\n\n**Core Dependencies:**\n- `bash` (version 4.0+)\n- `curl` (for API requests)\n- `jq` (for JSON parsing)\n\n**Optional:**\n- `gpsd` and `cgps` (for GPS hardware support)\n\n### Installing Dependencies\n\n**Debian/Ubuntu/Kali:**\n```bash\nsudo apt-get update\nsudo apt-get install -y bash curl jq\n\n# Optional: for GPS hardware\nsudo apt-get install -y gpsd gpsd-clients\n```\n\n**macOS:**\n```bash\nbrew install bash curl jq\n\n# Optional: for GPS hardware\nbrew install gpsd\n```\n\n**Arch Linux:**\n```bash\nsudo pacman -S bash curl jq gpsd\n```\n\n## 🚀 Installation\n\n### Quick Install\n\n```bash\ncd /home/kali/labs\ngit clone https://github.com/yourusername/gps-cli.git\ncd gps-cli\n./install.sh\n```\n\n### Manual Installation\n\n```bash\n# Make script executable\nchmod +x gps\n\n# Create symlink\nmkdir -p ~/.local/bin\nln -s $(pwd)/gps ~/.local/bin/gps\n\n# Add to PATH (if not already)\necho 'export PATH=\"$HOME/.local/bin:$PATH\"' \u003e\u003e ~/.zshrc  # or ~/.bashrc\nsource ~/.zshrc\n```\n\n### Verify Installation\n\n```bash\ngps help\n```\n\n## 🎯 Quick Start\n\n### 1. Setup Tracking Provider\n\n```bash\ngps setup\n```\n\nChoose **Traccar** (option 1), select the **FREE demo server**, and give your device a name (e.g., \"my-laptop\" or \"gps-tracker\")!\n\nThe device name will be used to identify your device in the Traccar dashboard.\n\n### 2. Start Tracking\n\n```bash\ngps start\n```\n\n### 3. Get Your Tracking URL\n\n```bash\ngps url\n```\n\nOpen the URL in any web browser to see your device on a map!\n\n### 4. Check Status\n\n```bash\ngps status\n```\n\n### 5. Stop Tracking\n\n```bash\ngps stop\n```\n\n## 📖 Usage\n\n### Commands\n\n| Command | Alias | Description |\n|---------|-------|-------------|\n| `gps setup` | - | Configure tracking provider |\n| `gps start` | - | Start GPS tracking |\n| `gps stop` | - | Stop GPS tracking |\n| `gps status` | `s` | Show tracking status and location |\n| `gps url` | `link` | Display tracking URL |\n| `gps config` | `configure` | Configure update interval |\n| `gps history` | `h` | Show location history |\n| `gps providers` | `list` | List available providers |\n| `gps help` | `-h`, `--help` | Show help message |\n\n### Examples\n\n**Start tracking with default settings:**\n```bash\ngps start\n```\n\n**Check your current status:**\n```bash\ngps status\n```\n\n**Get tracking URL to share:**\n```bash\ngps url\n```\n\n**Change update interval to 30 seconds:**\n```bash\ngps config\n# Enter: 30\n```\n\n**View location history:**\n```bash\ngps history\n```\n\n**List all providers:**\n```bash\ngps providers\n```\n\n## 🛠️ Providers\n\n### 1. Traccar (Recommended) 🌟\n\n**Best for:** Everyone - Easiest setup with free demo server\n\n**Setup:**\n1. Run `gps setup`\n2. Select option `1` (Traccar)\n3. Select option `1` (Free demo server)\n4. Enter a device name (e.g., \"gps-tracker\") or press Enter for auto-generated name\n5. Done! Your tracking URL will be displayed\n\n**Features:**\n- ✅ Free demo server (no registration)\n- ✅ Web-based map interface\n- ✅ Real-time tracking\n- ✅ Custom device names for easy identification\n- ✅ Osmand protocol for better device management\n- ✅ Self-hosted option available\n\n**Web Interface:**\n- Demo server: https://demo2.traccar.org\n- Login not required for viewing\n- Just use your device ID in the URL\n\n**Self-Hosting Traccar:**\n```bash\n# Docker installation\ndocker run -d --name traccar \\\n  -p 8082:8082 \\\n  -p 5055:5055 \\\n  traccar/traccar:latest\n```\n\nThen configure GPS CLI to use `http://your-server:8082`\n\n### 2. OwnTracks 🔒\n\n**Best for:** Privacy-conscious users with technical expertise\n\n**Requirements:**\n- MQTT broker (Mosquitto) or HTTP endpoint\n- Self-hosted OwnTracks Recorder for web interface\n\n**Setup:**\n1. Install Mosquitto MQTT broker\n2. Install OwnTracks Recorder\n3. Run `gps setup` and select OwnTracks\n4. Enter your endpoint URL\n\n**Installation (Server):**\n```bash\n# Install Mosquitto\nsudo apt-get install mosquitto mosquitto-clients\n\n# Install OwnTracks Recorder\n# See: https://github.com/owntracks/recorder\n```\n\n**Features:**\n- ✅ End-to-end encryption\n- ✅ Privacy-focused\n- ✅ MQTT or HTTP support\n- ⚠️ Requires own server\n\n### 3. PhoneTrack ☁️\n\n**Best for:** Nextcloud users\n\n**Requirements:**\n- Nextcloud instance\n- PhoneTrack app installed\n\n**Setup:**\n1. Install PhoneTrack on your Nextcloud\n2. Create a tracking session\n3. Get session token from PhoneTrack\n4. Run `gps setup` and select PhoneTrack\n5. Enter Nextcloud URL and session token\n\n**Installation (Nextcloud):**\n```bash\n# Install via Nextcloud app store or:\nsudo -u www-data php occ app:install phonetrack\n```\n\n**Features:**\n- ✅ Integrated with Nextcloud\n- ✅ Session-based tracking\n- ✅ Privacy-first design\n- ⚠️ Requires Nextcloud\n\n### 4. GPSLogger 🔧\n\n**Best for:** Custom integrations and developers\n\n**Requirements:**\n- HTTP endpoint that accepts POST requests\n\n**Setup:**\n1. Set up your custom endpoint\n2. Run `gps setup` and select GPSLogger\n3. Enter endpoint URL and auth token\n\n**Example Backend (Node.js/Express):**\n```javascript\napp.post('/gps/update', (req, res) =\u003e {\n  const { device_id, latitude, longitude, timestamp } = req.body;\n  // Store location in your database\n  res.json({ success: true });\n});\n```\n\n**Features:**\n- ✅ Maximum flexibility\n- ✅ Custom integrations\n- ✅ Any HTTP endpoint\n- ⚠️ DIY implementation\n\n## 📱 Mobile Devices\n\n### Android\n\n**Option 1: Traccar Client (Recommended)**\n1. Install \"Traccar Client\" from Google Play Store\n2. Open app → Settings\n3. Set Device Identifier to your GPS CLI device ID\n4. Set Server Address: `https://demo2.traccar.org:5055`\n5. Start tracking\n\n**Option 2: GPSLogger for Android**\n1. Install \"GPSLogger\" from F-Droid or Google Play\n2. Configure custom URL endpoint\n3. Enable automatic logging\n\n### iOS\n\n**OwnTracks for iOS**\n1. Install \"OwnTracks\" from App Store\n2. Configure HTTP endpoint or MQTT broker\n3. Set device ID and credentials\n4. Start tracking\n\n### Other Options\n\n- **Traccar Manager** - iOS/Android management app\n- **PhoneTrack** - Nextcloud mobile app\n- Any app that can POST to HTTP endpoints\n\n## ⚙️ Configuration\n\n### Config Location\n\nAll configuration is stored in `~/.config/gps-cli/`:\n- `config.json` - Main configuration\n- `history.json` - Location history\n- `gps.log` - Application logs\n- `.env` - Provider credentials (optional)\n- `tracker.pid` - Background process ID\n\n### Environment Variables\n\nCopy `.env.sample` to `~/.config/gps-cli/.env` for advanced configuration:\n\n```bash\ncp .env.sample ~/.config/gps-cli/.env\nnano ~/.config/gps-cli/.env\n```\n\n**Key Settings:**\n```bash\n# Update interval (seconds)\nUPDATE_INTERVAL=60\n\n# GPS source (auto, ip, hardware)\nGPS_SOURCE=auto\n\n# Provider selection\nGPS_PROVIDER=traccar\n```\n\n### Update Intervals\n\n```bash\n# Interactive configuration\ngps config\n\n# Common intervals:\n# 30  = 30 seconds (high frequency)\n# 60  = 1 minute (default, balanced)\n# 300 = 5 minutes (battery saving)\n# 600 = 10 minutes (low frequency)\n```\n\n## 🔧 Troubleshooting\n\n### Tracking Not Starting\n\n**Check dependencies:**\n```bash\nwhich curl jq\n```\n\n**Check configuration:**\n```bash\ncat ~/.config/gps-cli/config.json\n```\n\n**Check logs:**\n```bash\ntail -f ~/.config/gps-cli/gps.log\n```\n\n### Location Not Updating\n\n**Verify background process:**\n```bash\ngps status\n```\n\n**Check IP geolocation APIs:**\n```bash\ncurl -s https://ipapi.co/json/ | jq\n```\n\n**Restart tracking:**\n```bash\ngps stop\ngps start\n```\n\n### Tracking URL Not Working\n\n**Traccar demo server:**\n- URL format: `https://demo2.traccar.org/?id=YOUR_DEVICE_NAME`\n- Device must send at least one location update first\n- Wait 1-2 minutes after starting tracking\n- Device will appear in the dashboard with the name you chose during setup\n\n**Self-hosted:**\n- Verify server is accessible\n- Check firewall rules\n- Ensure correct port configuration\n\n### Permission Denied\n\n**Make script executable:**\n```bash\nchmod +x ~/.local/bin/gps\n```\n\n**Check PATH:**\n```bash\necho $PATH | grep .local/bin\n```\n\n### GPS Hardware Not Detected\n\n**Install gpsd:**\n```bash\nsudo apt-get install gpsd gpsd-clients\n```\n\n**Check GPS device:**\n```bash\nlsusb  # Look for GPS device\ncgps   # Test GPS reception\n```\n\n**Start gpsd:**\n```bash\nsudo gpsd /dev/ttyUSB0 -F /var/run/gpsd.sock\n```\n\n## 🔐 Privacy \u0026 Security\n\n### Data Storage\n\n- **Local only:** All configuration stored in `~/.config/gps-cli/`\n- **No cloud sync:** Data never leaves your device (unless you configure it)\n- **Open source:** Audit the code yourself\n\n### IP Geolocation\n\n- **Approximate:** City-level accuracy (5-50km radius)\n- **Third-party APIs:** ipapi.co and ip-api.com\n- **Limited data:** Only IP address sent to geolocation APIs\n- **Fallback:** Multiple providers for reliability\n\n### Provider Security\n\n| Provider | Privacy Level | Data Storage | Encryption |\n|----------|---------------|--------------|------------|\n| Traccar (demo) | ⚠️ Public | Demo server | HTTPS |\n| Traccar (self-hosted) | ✅ Private | Your server | HTTPS |\n| OwnTracks | ✅ Private | Your server | End-to-end |\n| PhoneTrack | ✅ Private | Your Nextcloud | HTTPS |\n| GPSLogger | 🤷 Depends | Your endpoint | Your choice |\n\n### Recommendations\n\n1. **For maximum privacy:** Use self-hosted OwnTracks or Traccar\n2. **For testing:** Traccar demo is fine (temporary use)\n3. **For existing setup:** PhoneTrack if you already use Nextcloud\n4. **For custom needs:** GPSLogger with your own backend\n\n## 🌐 Cross-Platform Support\n\n### Linux ✅\n- Fully supported\n- All providers available\n- GPS hardware support via gpsd\n\n### macOS ✅\n- Fully supported\n- All providers available\n- Limited GPS hardware support\n\n### Windows (WSL) ✅\n- Supported via WSL or MSYS2\n- All providers available\n- No GPS hardware support\n\n### Android 📱\n- Use Traccar Client app\n- Configure with same device ID\n- Points to same tracking URL\n\n### iOS 📱\n- Use OwnTracks app\n- Requires MQTT/HTTP setup\n- Alternative: Traccar iOS app\n\n## 📊 Use Cases\n\n### Personal Tracking\n- Track your laptop when traveling\n- Find lost devices\n- Monitor device location history\n\n### Asset Tracking\n- Track company equipment\n- Monitor fleet vehicles (with GPS hardware)\n- Logistics and delivery tracking\n\n### Development \u0026 Testing\n- Test location-based applications\n- Simulate device movement\n- API integration testing\n\n### Security \u0026 Backup\n- Emergency location tracking\n- Anti-theft monitoring\n- Backup location tracking\n\n## 🤝 Contributing\n\nContributions are welcome! Here's how you can help:\n\n1. **Report bugs:** Open an issue\n2. **Suggest features:** Start a discussion\n3. **Submit PRs:** Fork, code, and create pull request\n4. **Improve docs:** Fix typos, add examples\n5. **Share providers:** Add support for new tracking services\n\n## 📄 License\n\nThis project is free and open-source. Use, modify, and distribute as you wish.\n\n## 🙏 Acknowledgments\n\n- **Traccar:** Excellent open-source GPS tracking platform\n- **OwnTracks:** Privacy-focused location tracking\n- **PhoneTrack:** Great Nextcloud integration\n- **IP Geolocation APIs:** ipapi.co and ip-api.com\n\n## 📞 Support\n\n- **Documentation:** This README\n- **Issues:** GitHub Issues\n- **Discussions:** GitHub Discussions\n- **Logs:** Check `~/.config/gps-cli/gps.log`\n\n## 🗺️ Roadmap\n\n### v0.2.0 (Released)\n- [x] Device naming support\n- [x] Osmand protocol for Traccar\n- [x] Improved IP geolocation stability\n- [x] Better error handling and timeouts\n- [x] JSON parsing fixes\n\n### v0.3.0 (Planned)\n- [ ] Enhanced GPS hardware support\n- [ ] Multiple device tracking\n- [ ] Geofencing alerts\n- [ ] Export location data (CSV, KML)\n- [ ] Web dashboard\n\n### v0.4.0 (Future)\n- [ ] Bluetooth beacon support\n- [ ] Wi-Fi positioning\n- [ ] Battery optimization modes\n- [ ] Encryption for all providers\n- [ ] Mobile app companion\n\n## 📝 Version\n\nCurrent version: **0.2.0**\n\nSee [CHANGELOG.md](CHANGELOG.md) for version history.\n\n---\n\n**Made with ❤️ for privacy-conscious device tracking**\n\n🛰️ Track responsibly | 🔒 Privacy matters | 🌍 Location everywhere\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexcolls%2Fgps-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falexcolls%2Fgps-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexcolls%2Fgps-cli/lists"}