Getting started
Install
The CLI is a single ~300 KB executable for 64-bit Linux. It links
the system libcurl and OpenSSL, which any modern
distribution (Ubuntu 20.04+, Debian 11+, Fedora, Arch) already has.
Download it directly:
Put it on your PATH
Or grab it from the terminal and install it for every shell:
bash
curl -fLO https://geocanvas.dev/downloads/geocanvas-upload-linux-amd64
chmod +x geocanvas-upload-linux-amd64
sudo mv geocanvas-upload-linux-amd64 /usr/local/bin/geocanvas-upload
Verify the download against its checksum: run
sha256sum -c geocanvas-upload-linux-amd64.sha256 in
your download directory.
Windows and macOS
On Windows, the same Linux binary runs as-is inside WSL: install
any Ubuntu distribution from the Microsoft Store and follow the
Linux steps in it. There is no macOS build yet.
Setup
Log in with a CLI token
GeoCanvas accounts use emailed magic links, which do not exist in a
terminal. CLI access tokens stand in: create one under
Settings, CLI access tokens on the website, choose a
lifetime (24 hours, 7 days, or 30 days), and copy the
gcu_… value shown once.
The token is scope-locked to the upload endpoints, so it cannot read your
maps or change account settings. It is stored locally at
~/.config/geocanvas-upload/config.json with owner-only
permissions.
bash
geocanvas-upload login --token gcu_… --api https://geocanvas.dev
# Logged in as you@example.com (https://geocanvas.dev). Token saved to …
geocanvas-upload teams
# <team-id> owner Your Team <- copy the team id for uploads
Every day
Upload a file
Pass the file and your team id. The format kind is inferred from the
extension (.geojson .zip .gpkg .csv .parquet for vector,
.tif .tiff .png .jpg .jpeg .jp2 .img for raster); use
--kind when the extension does not say.
bash
geocanvas-upload upload /data/national-parks.geojson --team <team-id>
# Options:
# --kind vector|raster force the upload kind
# --name "Park trails" layer name in the catalog (default: file name)
# --concurrency 6 parallel part uploads
# --fresh discard any saved session and start over
# --wait-timeout-min 0 do not wait for server-side ingest to finish
Files up to 100 MiB go up in a single request; larger ones are split into
32 MiB parts uploaded through a sliding window of parallel connections.
Uploads travel straight from your machine to object storage: the server
only signs URLs and never relays the bytes. After the transfer, the CLI
triggers the same ingest pipeline the browser uses and reports progress
until the layer is ready in the catalog.
Resilience
Interrupted uploads resume
Every large upload writes a small <file>.gcupload.json
marker next to the data file, and uploaded parts are kept server-side for
seven days. If the connection drops, the laptop sleeps, or you press
Ctrl+C: run the exact same command again and only the missing parts are
resent.
bash
geocanvas-upload upload /data/national-parks.geojson --team <team-id>
# Resuming session 5338ffa2-…
# [############################------------] 83.0 MB/115 MB (3.1 MB/s, eta 10s)
geocanvas-upload sessions # list resumable uploads
geocanvas-upload abort <id> # discard a session and its saved parts
Transient failures (connection resets, 5xx responses) are
retried automatically with 0/1/3/5 second backoff. If a session was aborted
or has expired, the CLI tells you to re-run with --fresh.
Reference
Commands
| Command | What it does |
|---|
login --token <gcu_…> [--api URL] | Verify the token and save it locally (default api: https://geocanvas.dev) |
teams | List your teams with the ids uploads need |
upload <file> --team <id> | Upload and ingest a file; resumes an interrupted session for the same file |
sessions | List resumable upload sessions and their part-retention expiry |
abort <session-id> | Discard a session and any parts already stored |
Full source and tests live in
tools/geocanvas-upload/ in the repository, documented in
documentation/tools-upload-cli.md.