Note: This repo was uploaded to GitHub in order to showcase the feature-rich Bash CLI utility (with a Python app indicator system service) that I spent houdreds of hours of personal time working on as a side project over 3 years while working at GEOTAB. This tool saw widespread adoption and praise by developers at the company, with it becoming standard software for houndreds of developers and being said by management to have "significantly increased the productivity of the entire Development department". It was based on a CLI project that I developed while studying in university, which was essentially a framework for building Bash CLI utilitys.
This branch is the unrealeased version of what would have been
geo-cli 3.0, the next major release of the utility. The massive changes in the codebase and feature-set is comparable to the differences between Python 2 and Python 3 (huge changes/improvments, around 20,000 changes from the previous version). Unfortunantly, I didn't have time to finish it before leaving the company in 2023.
A tool that makes MyGeotab development easier. Specifically, this tool aims to simplify cross-release development by managing various versions of geotabdemo Postgres database containers. This allows developers to easily switch between release branches without having to worry about database compatibility.
The tool has also evolved over the years to include a taskbar UI menu as well as many time-saving features that simplify other pain points of daily development by automating them; providing an easy-to-use interface that hides the complexity under the hood and makes developers more productive.
geo-cliis currently under active development and is updated often. Feel free to make an MR if you would like to contribute improvements or features.Note:
geo-cliis only supported on Ubuntu. However, it can be made to work in WSL on Windows if you set up docker for it.
💬 Join the geo-cli Chat Space here (currently with more than 80 members) to report bugs, share feature ideas, and stay informed about new features. You can also contact me on Chat or through email ([email protected]).
⭐ Like geo-cli? Add a star to the repo.
If running in a bash sell, geo-cli has extensive support for tab completion (double pressing the Tab key). It will show you what commands/subcommands are available, as well as possible command arguments for certain commands such as geo db start/rm.
Completion for geo shows all commands available:
$ geo <double press tab>
analyze edit id mydecoder stop
ar env image myg test
cd get indicator quarantine uninstall
db gw init rm update
dev help loc set versionCompletion for geo db start will show all of your databases (that you created with geo-cli) that can be started:
$ geo db start
6_0 7_0 8.0 9.0 91 Lets say that you're developing a new feature on a 2004 branch of MyGeotab, but have to switch to a 2002 branch for a high priority bug fix that requires the use of geotabdemo (or any compatible database, for that matter). Switching to a compatible database is as simple as checking out the branch, building the project (only required when creating a new db container), and then running the following in a terminal:
geo db start 2002
2002in the above command is just a name that you pick for the container and volume thatgeocreates for you; it can be any alphanumeric name (including underscores and hyphens) you like. If a db container with that name already exists, it will just start that one instead of creating a new one.
The output of this command is shown below:
Under the hood,
geois creating a Postgres container and a data volume for it. The tool then starts the container, mounted with the data volume, and then initializesgeotabdemoon it usingdotnet CheckmateServer.dll CreateDatabase postgres .... This is why you have to build the project for a certain release branch before creating a new db container.
Now you may run geotabdemo or any tests that require a 2002 database version.
When you're done with the bug fix and want to resume working on your 2004 feature, switch back to your 2004 branch and run the following in a terminal:
geo db start 2004The output of this command is shown below:
Navigate to your directory of choice in a terminal and clone this repo
git clone [email protected]:dawsonmyers/geo-cli.gitNext, navigate into the repo directory
cd geo-cliAnd finally, if you are in a bash shell, run the following command to execute the install script.
source install.shIf you use a shell other that bash, the install must be run like this:
bash install.shThe installer will add support for zsh and fish to their corresponding config files. If you use a different shell, add the following alias to its config file:
alias geo="bash <full path geo-cli repo dir>/src/geo-cli.sh"Docker is required for
geoto work. You will be prompted to install it during the install process if it is missing. You must completely log out and then back in again after a Docker install for the new permissions to take effect.
You will be asked to enter the location of Development repo during the install. The tool needs to know where this is so that it knows the location of:
- The CheckmateServer dll used for initializing
geotabdemo - The Dockerfile used to create the base Postgres image used to build the db containers
The tool will also build the base Postgres image during the install process, so it may take several minutes to complete (even longer if you also have to install Docker).
A simple install (where I already have Docker installed and have created the base db image) is shown below:
Now you can open a new terminal or run . ~/.bashrc to re-source .bashrc in your current one to begin using geo.
Now that geo-cli is installed, you can begin using it for creating and running various database versions for your development needs.
The first thing that you want to do after installing the tool is to create a database. The MyGeotab Postgres database will be created using CheckmateServer.dll from the current branch that you have checked out. geo will automatically build MyGeotab.Core so that the correct dll will be used for initializing the database.
Next, we will create, initialize, and start your first database. You will have to give it an alphanumeric name to identify it (the MyGeotab release version is usually the best name to use, e.g., 2004). So, assuming that you're working on a 2004 branch of MyGeotab, a database could be created by entering the following in a terminal:
geo db start 2004You will be prompted to stop Postgres if you have it running locally or in a container. This is so that port 5432 can be made available for a
geo-clidatabase.
The output is shown below:
You can choose to use a different Postgres version via the
-v <pg_version:int>argument (e.g.geo db start -v 14 <db_container_name>)
After creating a geo-cli database container, you will be shown instructions on how to import a server configuration into gpAdmin. The following gif demonstrates this process.
Note: You only have to import the server configuration once. It will work with any
GeotabDemodatabase that's running.
You can make a copy of a geo-cli database using:
geo db cp <source> <destination>Example:
$ geo db cp 8.0 8.0-copy
Creating destination database volume '8.0-copy'
Copying data from source database volume '8.0' to '8.0-copy'
✔️ Done
Creating destination database container '8.0-copy'
✔️ Done
You can list your geo-cli databases using:
geo db ls
The following command will remove the 2001 database from geo-cli:
geo db rm 2001
You can confirm that the 2001 database has been removed by listing your geo-cli databases:
geo db ls
You can delete all databases using geo db rm --all/geo db rm -a. You will be prompted before continuing. Additionally, you can add a filter to the command. For instance, if you wanted to remove all databases that contain the string test, you would use geo db rm -a test.
geo-cli can also be used to create empty databases for any use case you may encounter:
This creates a MyGeotab postgres db with the sql admin as geotabuser and the password as vircom43.
If you would like a completely empty Postgres 12 db (or any PG version using the -v <version:int> option) without any initialization, add the -e option to the command, e.g., geo db create -e <name>.
The default user for the database is postgres and the password is password. This username/password can be used to connect to the db (once started) using pgAdmin or psql (using geo db psql) . This database is just a plain, off-the-shelf Postgres database container (built from the official Postgres docker image), you can use it for anything: to experiment with or even for use with a side project, if you like. geo-cli will make sure that only one database container is running at a time, ensuring that the required port, 5432, is always available.
The
geo db createcommand does not start the container after creating it. Usegeo db start <name>to start it.
pgAdmin can be used to interact with the database, or geo db psql can be used to start an interactive psql session with a running database container. If you just want to run a single query, you can use the -q option to specify a sql query:
geo db psql -q 'SELECT * FROM deviceshare'Note: The query must be enclosed in single quotes
Want to run analyzers locally instead of pushing to GitLab and waiting for the pipeline to fail?. geo analyze saves you a ton of time by easily letting you do this:
geo analyzeThis will output the selection menu and prompt you for which analyzers you want to run:
So if you wanted to run CSharp.CodeStyle and StyleCop.Analyzers you would type 0 4 and press enter:
The output is then displayed as the analyzers are run:
The following options can be used with geo analyze:
- - This option will reuse the last test ids supplied
- -a This option will run all tests
- -s Skips long-running analyzers (GW-Linux-Debug and Build-All.sln), allowing you to quickly check your code before pushing it to GitLab
I aliased
geo analyze -astogaa(via addingalias gaa='geo analyze -as'to~/.bashrc) to allow me to quickly run all analyzers (excluding the long-running ones) before pushing changes by opening up any terminal and runninggaa. You can add this alias to your .bashrc file if you like with this command:echo "alias gaa='geo analyze -as'" >> ~/.bashrc. You can also quickly pastealias gaa='geo analyze -as'into your .bashrc file by usinggeo-ui's Edit > .bashrc menu item. This will open up the .bashrc file in a text editor.
geo-cli can be used to simplify connecting to servers over IAP tunnels. First, make an access request for a server using MyAdmin. Then copy gcloud compute start-iap-tunnel command by pressing the copy button:
geo ar createcan be used to open up the My Access Request page on the MyAdmin website in Chrome. This page can be used to create a new access request.
After that, paste the gcloud command in a terminal as an argument to geo ar tunnel as shown below:
geo-cliwill remember the gcloud command so that you can re-open the tunnel by running justgeo ar tunnelwithout the gcloud command. It also remembers the port that the tunnel is running on so that you don't have to include it when runninggeo ar ssh
Now you can open another terminal and run the geo ar ssh command to ssh into the server:
By default, the username stored in th $USER environment variable is used when connecting to the server with
geo ar ssh. You can set the default username by supplying it with the-u <username>option. You can also use a different port using the-p <port>option.
You can add the -L option to either geo ar tunnel or geo ar ssh to bind local port 5433 to 5432 on remote host (through IAP tunnel). You can connect to the remote Postgres database using this port (5433) in pgAdmin. Note: you can also open up an ssh session to this server by opening another terminal and running geo ar ssh.
Now you can connect to the Postgres database in pgAdmin by creating a server via Objects > Register > Server. Then enter in the following information:
- Host: localhost
- Port: 5433
- username: <your username (what comes before @geotab.com in you email)>
- Password:
Use the geo id <id> command to both encode and decode long and guid ids to simplify working with the MyGeotab api. The result is copied to your clipboard (if you have xclip installed). Guid encoded ids must be prefixed with 'a' and long encoded ids must be prefixed with 'b'"
Long Encode
$ geo id 1234
Encoded long id:
b4d2
copied to clipboardLong Decode
$ geo id b4d2
Decoded long id:
1234
copied to clipboardGuid Encode
$ geo id 00e74ee1-97e7-4f28-9f5e-2ad222451f6d
Encoded guid id:
aAOdO4ZfnTyifXirSIkUfbQ
copied to clipboardGuid Decode
$ geo id aAOdO4ZfnTyifXirSIkUfbQ
Decoded guid id:
00e74ee1-97e7-4f28-9f5e-2ad222451f6d
copied to clipboardYou can also convert multiple ids in a single line, regardless of whether decoding or encoding is required.
$ geo id 1234 b4d2 aAOdO4ZfnTyifXirSIkUfbQ
b4d2
1234
00e74ee1-97e7-4f28-9f5e-2ad222451f6d
copied to clipboardThe geo test <filter> command can be used to run tests on your local build. The filter behaves the same as in dotnet test --filter. By default, tests matching the given filter will be run on your local machine. When run with the -d or --docker option, the tests will be run in a docker container which matches the one used in CI/CD pipelines instead. This option requires docker to be logged into gitlab, and is only supported from 9.0 onwards.
Go to https://git.geotab.com/-/profile/personal_access_tokens and create a token with api access and copy the PAT to your clipboard. Make sure to also make a note of the PAT somewhere safe since you won't be able to view it again.
Now we are going set up the required environment variables. Run the following command:
geo init patPaste in your PAT and enter your GitLab username when prompted.
Your GitLab username is what comes before @geotab.com, e.g., my email is [email protected], so I would enter dawsonmyers as my username.
Next, we'll use your PAT to log into the GitLab docker container registry.
docker login git.geotab.com:4567You will then be prompted for your GitLab username and a password. Paste (Ctrl + Shift + V) the access token in your clipboard when asked for the password.
Use geo quarantine <FullyQualifiedTestName> to quickly add quarantine attributes to a broken test.
Before running geo quarantine ...:
[Fact]
public void Test()
{After:
[Fact]
[Trait("TestCategory", "Quarantine")]
[Trait("QuarantinedTestTicketLink", "")]
public void Test()
{geo quarantine [options] <FullyQualifiedTestName>
Adds quarantine attributes to a broken test and, optionally, commits the test file.
Options:
-b
Only print out the git blame for the test.
-c
Commit the file after adding the annotations to it.
-m <msg>
Add a custom commit message. If absent, the default commit
message will be "Quarantined test $testclass.$testname".
Example:
geo quarantine -c CheckmateServer.Tests.Web.DriveApp.Login.ForgotPasswordTest.Test
geo quarantine -c -m 'Quarentine test' CheckmateServer.Tests.Web.DriveApp.Login.ForgotPasswordTest.Testgeo mydecoder <MyDecoderExportedJsonFile> converts device data from MyDecoder (exported as JSON) into a MyGeotab text log file. Here are a couple ways that these log files can be processed by MyGeotab to reproduce bugs:
- Copy the converted log file into the
~/GEOTAB/Checkmate/geotabdemo_dataso that MyGeotab will ingest the log file as if it had come from the Gateway. - Set up a test that will process it as a file data source through the DDIS.
To convert device data from MyDecoder into a MyGeotab text log file, export the data from MyDecoder to JSON by clicking on the Export Data button as shown in the image below:
Then, open up a terminal in the JSON file's directory and run geo mydecoder <filename.json>. After the command has run, the output file will be in the same directory, with the same name, but with a .txt file extension. This file can be processed by MyGeotab just like any other log file.
You can also convert a JSON file by right clicking on it and selecting the Scripts > [geo-cli] MyDecoder JSON To Txt option.
Note: This feature is only available for MYG 9.0 and above, so you must have a compatible version of MYG checked out for it to work.
Run the geo gw command with desired options to build, start, stop, restart or clean a standalone Gateway. These options can also be accessed in the UI menu under Gateway.
Note: The
geo-uiicon will contain a blue dot when the Gateway is running and/or a green dot when MyGeotab is running.
Run the geo myg gw command to run MyG along with Gateway. This will create an empty database with the provided <databaseName>, insert a device into the vehicle table, update the server.config and storeforward.config with required changes, and copy certs (may require sudo login).
Similarly, you can also accomplish this using the MyGeotab > Run with Gateway in the geo-ui menu.
You can restart a MyGeotab and Gateway configuration at a later date by clicking on the
MyGeotab > Run with Gatewaygeo-uimenu item and then typing in the same company name and database container name when prompted.
Once you have MyG and GW running, send a multilog message to the device using deviceConnectAndListen_2.py:
python3 deviceConnectAndListen_2.py activateTo verify the connection, open https://127.0.0.1:10001/\ via the MyGeotab > Open In Browser geo-ui menu item. Then, navigate to Engine & Maintenance > Engine & Device > Measurements in the web UI and apply a filter for the current date. You should now see one command listed as shown in the image below:
Note: If no command is listed, you might also want to check if using port 443 is enforced and update to allow using a port other than 443.
Run the geo init git-hook command to add the prepare-commit-msg git hook that prepends the MYG issue number to each commit you make. It parses the issue number from the branch name.
geo cmd <create|rm|ls|edit>Have you identified a manual development process or repetitive task that you think could be automated through scripting? Or maybe you've already created a script of your own that saves you time and would like to share it with others? Well adding it to geo-cli is a great way to make it conveniently available to the entire Development department.
This is where the geo cmd command comes in, it greatly simplifies adding features to geo-cli by scaffolding out a new command for you. Just run geo cmd create <command> to initialize and register the command with geo-cli. By the time the create command completes, VS Code can be automatically opened to the new command's template file (to add its logic) and you'll be able to access it in any terminal by running geo <command>. A branch for the new command can also be created for you during the setup process.