trailcli

A CLI tool for planning hiking, biking, and walking routes using OpenStreetMap data.

Usage

uvx trailcli --help

# Geocode a place name
trailcli geocode "Koblenz Hauptbahnhof" --country de

# Reverse geocode coordinates
trailcli reverse 50.3569 7.5890

# Route between two points
trailcli route 50.27 7.72 50.23 7.71 --costing pedestrian --output hike.gpx

# Stitch GPX files together
trailcli stitch approach.gpx trail.gpx exit.gpx --output dayhike.gpx

# Generate an HTML map
trailcli map dayhike.gpx --output dayhike.html --title "Rhine Day Hike"

Run trailcli --help for full documentation of all commands and options.

API Services

This tool relies on free, community-run OpenStreetMap services. Please use them responsibly and respect their rate limits (1 request/second). If you find them useful, consider donating to keep them running.

• Nominatim — Geocoding and reverse geocoding. Donate to OpenStreetMap
• Valhalla (FOSSGIS) — Routing engine for hiking, biking, and driving. Donate to FOSSGIS

Developing Setup

Install uv and git and run the following commands to download the code and setup everything.

git clone https://github.com/piebro/trailcli.git
cd trailcli
uv sync
uv run pre-commit install

Publishing

Update the version in pyproject.toml, commit, and then tag and push:

git tag v0.2.0
git push origin v0.2.0

A GitHub Action will automatically build and publish the new version to PyPI.

Contributing

Contributions are welcome. Open an issue if you want to report a bug or have a feature request.

License

All code in this project is licensed under the MIT License.