This article will go through the basic usage of gentoo_update CLI tool and the mobile app.

But before that, here is a demo of this project:

⚠️ CLI was rewritten in version 0.2.2 and the video is slightly outdated
Commands in this article were updated to the new CLI standard
Video will be updated soon 😼  

gentoo_update CLI App


gentoo_update is available in GURU overlay and in PyPI. Generally, installing the program from GURU overlay is the preferred method, but PyPI will always have the most recent version.

Enable GURU and install with emerge:

# enable the repository and sync package tree
eselect repository enable guru
emerge --sync

# unmask package, since all packages in GURU are considered unstable
echo 'app-admin/gentoo_update ~amd64' > /etc/portage/package.accept_keywords/gentoo_update

# install
emerge --ask app-admin/gentoo_update

Alternatively, install from PyPI with pip:

python -m venv .venv_gentoo_update
source .venv_gentoo_update/bin/activate
python -m pip install gentoo_update


gentoo_update provides 2 update modes - full and security. Full mode updates @world, and security mode uses glsa-check to find security patches, and installs them if something is found.

By default, when run without flags security mode is selected:

gentoo-update update

To update @world, run:

gentoo-update update --update-mode full

Full list of available parameters and flags can be accessed with the --help flag. Further examples are detailed in the repository’s readme file.

Once the update concludes, a log file gets generated at /var/log/portage/gentoo_update/log_<date> (or whatever $PORTAGE_LOGDIR is set to). This log becomes the basis for the update report when the report subcommand is used, transforming the log details into a structured update report.

Send Report

The update report can be sent through three distinct methods: IRC bot, email, or mobile app.

IRC Bot Method
Begin by registering a user on an IRC server and setting a nickname as outlined in the documentation. After establishing a chat channel for notifications, define the necessary environmental variables and execute the following commands:

export IRC_CHANNEL="#<irc_channel_name>"
export IRC_BOT_NICKNAME="<bot_name>"
export IRC_BOT_PASSWORD="<bot_password>"
gentoo-update report --send-report irc

Email via Sendgrid
To utilize Sendgrid, register for an account and generate an API key). After installing the Sendgrid Python library from GURU, save the API key in the environmental variables and use the commands below:

emerge --ask dev-python/sendgrid
export SENDGRID_TO='[email protected]'
export SENDGRID_FROM='[email protected]'
export SENDGRID_API_KEY='SG.****************'
gentoo-update report --send-report email

Email via local relay gentoo-update works well with existing email relaying tools, such as msmtp. Detailed guide on how to set it up can be found here.

After relay is up, output from the app can be piped to it like so:

echo -e "Subject: Gentoo Update Report\n\n$(gentoo-update report)" | msmtp -a default <target-email>

Notifications can also be sent via the mobile app. Details on this method will be elaborated in the following section.


gentoo_update Mobile App


Mobile app can either be installed from GitHub or Google Play Store.

Play Store
App can be found by searching gentoo_update in the Play Store, or by using this link.

Manual Installation
For manual installation on an Android device, download the APK file from
Releases tab on GitHub. Ensure you’ve enabled installation from Unknown Sources before proceeding.


The mobile app consists of three screens: Login, Reports, and Profile.

Upon first use, users will see the Login screen. To proceed, select the Anonymous Login button. This action generates an account with a unique user ID and token, essential for the CLI to send reports.

The Reports screen displays all reports sent using a specific token. Each entry shows the update status and report ID. For an in-depth view of any report, simply tap on it.

On the Profile screen, users can find their 8-character token, which needs to be saved as the GU_TOKEN variable on the Gentoo instance. This screen also shows the AES key status, crucial for decrypting the client-side token as it’s encrypted in the database. To log out, tap the Sign Out button.
Note: Since only Anonymous Login is available, once logged out, returning to the same account isn’t possible.

Gentoo Update Mobile App Screens



Preferred method for getting help or requesting a new feature for both CLI and mobile apps is by creating an issue in Github:

Or just contact me directly via [email protected] and IRC. I am in most of the #gentoo IRC groups and my nick is #LabBrat.


  • [Link] - gentoo_update CLI repository
  • [Link] - Mobile App repository