CLI reference

trackiwi <command>, or python3 -m trackiwi <command> from a clone. trackiwi <command> --help is authoritative for options. Source: trackiwi/cli.py (build_parser).

Commands

Command	Reads	Writes	What it does
login [--email E] [--token T --api-base URL]	stdin, terminal	config file	Authenticate and store the session. --token - reads the token from stdin. --token and --api-base must be given together.
logout	config file	removes config file	Revoke the session on the server, then remove the local credentials.
trackers	API	nothing	List devices: id, name. Not cached.
tours	API	nothing	List recorded tours: id, name, tracker id, start, end. Not cached.
alarms	API	nothing	List alarms: id, tracker id, type, acknowledged, recorded at. Prints no coordinates. Not cached.
markers	API	nothing	List markers: id, name (field names unverified). Not cached.
marker-categories	API	nothing	List marker categories: id, name, colour. Not cached.
shares	API	nothing	List active share links: id, name (field names unverified). Cannot create or revoke one. Not cached.
sync [--full]	API	cache	Fetch new positions into the cache; --full restarts from the beginning.
export --format F [--from D] [--to D] [--tracker N] [-o PATH]	cache	stdout or file	Export cached positions. See export formats.
heading [--tracker N] [--stale-after SECONDS] [--min-speed KMH]	cache	nothing	Estimate each vehicle’s heading from the cache. Offline. Defaults: --stale-after 3600, --min-speed 2 (a slower fix is GPS jitter).
influx check	InfluxDB	nothing	Probe the configured InfluxDB target: connectivity, auth, bucket.
influx push	cache	InfluxDB, mirror_state	Send cached positions not yet mirrored.
ingest	API, cache	cache, InfluxDB	sync, refresh tracker names, then influx push. What the timer runs.
purge --yes	nothing	removes cache	Delete the position cache and its -journal, -wal, -shm sidecars without opening it.

export and purge never create the cache. export takes --format (required, gpx, geojson or csv). --from and --to are inclusive UTC days, YYYY-MM-DD.

The tab-separated listings print a field the API does not send as -. Timestamps in the listings are printed as the API sends them (ISO 8601), not as epoch seconds.

Exit codes

Code	Meaning
0	Success.
1	Error: network, API, bad arguments to the tool’s own logic, an interrupted run, or a dead output stream (except in export, where an early-closing reader is success).
2	Authentication required: not logged in, or the session was rejected.

argparse also exits 2 for its own usage errors (an unknown flag, a missing --format), so a 2 alone does not prove an authentication failure. Check stderr: it says authentication required: ... for the real thing.

Files and environment

What	Default location	Notes
Session	~/.config/trackiwi/config.json	Mode 0600 in a 0700 directory. Honours XDG_CONFIG_HOME. Holds the API base, token and user id, never the password.
Position cache	~/.local/share/trackiwi/positions.db	SQLite, mode 0600 in a 0700 directory. Honours XDG_DATA_HOME. Holds positions, mirror_state, tracker_names.
InfluxDB target	~/.config/trackiwi/influx.toml	Mode 0600. Template: examples/influx.example.toml.
TRACKIWI_INFLUX_<KEY>	environment	Overrides the same key in influx.toml (url, org, bucket, token_env). Precedence: environment, then file, then default.
TRACKIWI_INFLUX_TOKEN	environment	The InfluxDB 2.x token, unless token_env names another variable.
TRACKIWI_INGEST_INTERVAL	compose environment	Seconds between runs of the ingest container (default 600).

The requirements behind these rules are in the requirements; the units table explains the position fields.