Command Line Usage¶
Overview¶
Assuming a normal install, the command-line client is called gaiagps
and is self-documenting. For
example, this gives an overview of global options and the top-level commands:
$ gaiagps --help
Traceback (most recent call last):
File "/home/docs/checkouts/readthedocs.org/user_builds/gaiagpsclient/envs/latest/bin/gaiagps", line 33, in <module>
sys.exit(load_entry_point('gaiagpsclient==0.1.1', 'console_scripts', 'gaiagps')())
File "/home/docs/checkouts/readthedocs.org/user_builds/gaiagpsclient/envs/latest/lib/python3.7/site-packages/pkg_resources/__init__.py", line 474, in load_entry_point
return get_distribution(dist).load_entry_point(group, name)
File "/home/docs/checkouts/readthedocs.org/user_builds/gaiagpsclient/envs/latest/lib/python3.7/site-packages/pkg_resources/__init__.py", line 2846, in load_entry_point
return ep.load()
File "/home/docs/checkouts/readthedocs.org/user_builds/gaiagpsclient/envs/latest/lib/python3.7/site-packages/pkg_resources/__init__.py", line 2450, in load
return self.resolve()
File "/home/docs/checkouts/readthedocs.org/user_builds/gaiagpsclient/envs/latest/lib/python3.7/site-packages/pkg_resources/__init__.py", line 2456, in resolve
module = __import__(self.module_name, fromlist=['__name__'], level=0)
File "/home/docs/checkouts/readthedocs.org/user_builds/gaiagpsclient/envs/latest/lib/python3.7/site-packages/gaiagpsclient-0.1.1-py3.7.egg/gaiagps/shell/__init__.py", line 12, in <module>
from gaiagps.shell import command
File "/home/docs/checkouts/readthedocs.org/user_builds/gaiagpsclient/envs/latest/lib/python3.7/site-packages/gaiagpsclient-0.1.1-py3.7.egg/gaiagps/shell/command.py", line 4, in <module>
import prettytable
File "/home/docs/checkouts/readthedocs.org/user_builds/gaiagpsclient/envs/latest/lib/python3.7/site-packages/prettytable-3.8.0-py3.7.egg/prettytable/__init__.py", line 47, in <module>
import importlib.metadata
ModuleNotFoundError: No module named 'importlib.metadata'
The client attempts to login to gaiagps.com as infrequently as possible and stores session information
to reduce the frequency of having to provide credentials. However, the first time user will have to login
at least once, and any time the session expires. To do this the first time, use the test
command:
gaiagps --user user@domain.com test
Password:
Success!
Afterwards, you need not provide your username for subsequent usage (until your session expires):
gaiagps test
Success!
Commands¶
The utility is arranged hierarchically with top-level commands, some
of which have sub commands. For example, the waypoint
command has
multiple sub-commands for things like add
, rename
, remove
,
etc:
gaiagps waypoint add 'My Campsite' 45.124 -122.987
gaiagps waypoint rename 'My Campsite' 'Cool Campsite'
gaiagps waypoint remove 'Cool Campsite'
For the primary data types that Gaia stores, the waypoint
,
track
, and folder
commands provide the bulk of the
functionality of the utility. Each command has its own --help
output, which tells you what you can do with each thing. For example:
$ gaiagps folder --help
Traceback (most recent call last):
File "/home/docs/checkouts/readthedocs.org/user_builds/gaiagpsclient/envs/latest/bin/gaiagps", line 33, in <module>
sys.exit(load_entry_point('gaiagpsclient==0.1.1', 'console_scripts', 'gaiagps')())
File "/home/docs/checkouts/readthedocs.org/user_builds/gaiagpsclient/envs/latest/lib/python3.7/site-packages/pkg_resources/__init__.py", line 474, in load_entry_point
return get_distribution(dist).load_entry_point(group, name)
File "/home/docs/checkouts/readthedocs.org/user_builds/gaiagpsclient/envs/latest/lib/python3.7/site-packages/pkg_resources/__init__.py", line 2846, in load_entry_point
return ep.load()
File "/home/docs/checkouts/readthedocs.org/user_builds/gaiagpsclient/envs/latest/lib/python3.7/site-packages/pkg_resources/__init__.py", line 2450, in load
return self.resolve()
File "/home/docs/checkouts/readthedocs.org/user_builds/gaiagpsclient/envs/latest/lib/python3.7/site-packages/pkg_resources/__init__.py", line 2456, in resolve
module = __import__(self.module_name, fromlist=['__name__'], level=0)
File "/home/docs/checkouts/readthedocs.org/user_builds/gaiagpsclient/envs/latest/lib/python3.7/site-packages/gaiagpsclient-0.1.1-py3.7.egg/gaiagps/shell/__init__.py", line 12, in <module>
from gaiagps.shell import command
File "/home/docs/checkouts/readthedocs.org/user_builds/gaiagpsclient/envs/latest/lib/python3.7/site-packages/gaiagpsclient-0.1.1-py3.7.egg/gaiagps/shell/command.py", line 4, in <module>
import prettytable
File "/home/docs/checkouts/readthedocs.org/user_builds/gaiagpsclient/envs/latest/lib/python3.7/site-packages/prettytable-3.8.0-py3.7.egg/prettytable/__init__.py", line 47, in <module>
import importlib.metadata
ModuleNotFoundError: No module named 'importlib.metadata'
Folder Organization¶
Gaia organizes data loosely into a hierarchical structure. By default, all data items live at the “root” level, but can be moved into folders. Folders can also be moved into folders, creating an arbitrarily deep tree structure. For example, to create a folder and move a waypoint into that folder, do the following:
gaiagps folder add 'My Folder'
gaiagps waypoint move 'Cool Campsite' 'My Folder'
Note
Removing a folder will remove all the contents of that folder, including other folders. Use caution when removing folders!
Some operations that create data allow those items to be automatically moved into a new or existing folder. For example, to create a new folder inside another folder, you would:
gaiagps folder add --existing-folder 'My Folder' 'Subfolder'
When you create a waypoint, you can add it to an existing folder, or create new folder at the same time:
gaiagps waypoint add --new-folder 'My New Folder' 'Trailhead' 45.321 -122.9012
Duplicate Names¶
Gaia allows you to create data objects with identical names. This makes it hard to distinguish one from the other, both in the web UI as well as at the command line. If you get into a situation where you have multiple objects with the same name, some work is required to disambiguate them. Consider the following scenario:
gaiagps waypoint list
+--------------------------------+----------------------+------------------+
| Name | Updated | Folder |
+--------------------------------+----------------------+------------------+
| My Campsite | 20 Apr 2019 02:58:21 | |
| My Campsite | 19 Apr 2019 03:41:53 | |
+--------------------------------+----------------------+------------------+
Here we have two waypoints called “My Campsite”. If I wanted to take action on on of them, say move it into a folder, I am unable to specify the name:
gaiagps waypoint move 'My Campsite' 'My Folder'
Multiple items with title=My Campsite found
In this case, assume I was on a weekend camping trip and I marked the campsite where we stayed each night on my tablet. Not thinking about it, I named them the same thing. Now, months later, I want to suggest one of those sites to a friend, but I don’t remember which was which. The timestamp of the waypoint may be enough to determine which is which, but maybe not. Either way, the steps for renaming one or both are:
- Get the unique ID of each one
- Confirm which one is which
- Rename one of them using the ID instead of the name
To show the items with names and IDs, use the --by-id
option to
list:
gaiagps waypoint list --by-id
6e87d380-00a0-44b0-9b01-b127dc8e0ffe 20 Apr 2019 02:58:21 'My Campsite'
7568434e-c9e3-42b4-b65f-29a855087672 19 Apr 2019 03:41:53 'My Campsite'
If the timestamp is enough to know which campsite is which, then you now have the ID necessary for the rename step. If the timestamp is not sufficient, you can get the browser-friendly URL of the item, by id, and look at it in the Gaia web UI to figure it out:
gaiagps waypoint url 6e87d380-00a0-44b0-9b01-b127dc8e0ffe
https://www.gaiagps.com/datasummary/waypoint/6e87d380-00a0-44b0-9b01-b127dc8e0ffe
To continue the example, I now have enough information to know that the first campsite from 20-April-2019 is the one I want to share. In order to change the name of it to distinguish it from the other, I can use the ID:
gaiagps waypoint rename 6e87d380-00a0-44b0-9b01-b127dc8e0ffe 'Awesome Campsite'
Now, my waypoint list looks like this:
gaiagps waypoint list
+--------------------------------+----------------------+------------------+
| Name | Updated | Folder |
+--------------------------------+----------------------+------------------+
| Awesome Campsite | 20 Apr 2019 02:58:21 | |
| My Campsite | 19 Apr 2019 03:41:53 | |
+--------------------------------+----------------------+------------------+
Since they now have different names, I can now manage them each by their name.
Matching and Bulk Operations¶
Some commands support operating on multiple items at once. For example, you can move multiple waypoints into a folder in a single command:
gaiagps waypoint move 'Campsite' 'Trailhead' 'Summit' 'My Hike'
Further, you can also use a regular expression to select multiple items to operate on:
gaiagps waypoint move --match 'Camp.*' 'All Campsites'
Note
Matching with a regular expression is very powerful, but has the
potential to let you do a lot of damage very easily. Exercise
caution when using this feature. When possible, use --dry-run
to
confirm planned actions before executing.
Some commands also support matching by date. This can be done by specifying a single date, or an inclusive date range. As an example, a large list of waypoints can be filtered into just a few from a trip with this strategy:
gaiagps waypoint list --match-date 2019-04-10
+--------------------------------+----------------------+------------------+
| Name | Updated | Folder |
+--------------------------------+----------------------+------------------+
| Trailhead | 10 Apr 2019 18:56:19 | |
| Lunch Spot | 10 Apr 2019 18:52:56 | |
| Summit | 10 Apr 2019 17:33:50 | |
+--------------------------------+----------------------+------------------+
gaiagps waypoint list --match-date 2019-04-10:2019-04-12
+--------------------------------+----------------------+------------------+
| Name | Updated | Folder |
+--------------------------------+----------------------+------------------+
| Trailhead | 10 Apr 2019 18:56:19 | |
| Lunch Spot | 10 Apr 2019 18:52:56 | |
| Summit | 10 Apr 2019 17:33:50 | |
| Swimming hole | 11 Apr 2019 12:18:22 | |
| Gas Station | 12 Apr 2019 14:02:11 | |
+--------------------------------+----------------------+------------------+
Date ranges can be open-ended, which means “everything before this date” or “everything after this date”:
gaiagps waypoint list --match-date 2019-04-12:
+--------------------------------+----------------------+------------------+
| Name | Updated | Folder |
+--------------------------------+----------------------+------------------+
| Gas Station | 12 Apr 2019 14:02:11 | |
| Community Park | 19 Apr 2019 11:26:32 | |
+--------------------------------+----------------------+------------------+