Provided by: gcli_2.9.1-1_amd64 
Installing GCLI
Through package manager
If you’re on FreeBSD you can just install gcli by running the following command:
# pkg install gcli
On NetBSD you can run:
# pkgin install gcli
On Ubuntu, Debian, Devuan and the like you can run:
# apt install gcli
On ArchLinux you can either use the AUR manually or use your favourite AUR helper:
# yay -S gcli
Compile the source code
Other operating systems may currently require manual compilation and installation.
Windows NT Notes
It is entirely possible to build gcli on Windows using MSYS2. Please follow their instructions on how to
set up a development environment.
Generic build instructions
For this purpose go to https://herrhotzenplotz.de/gcli/releases and choose the latest release. Then
download one of the tarballs.
For version 1.1.0 this would be:
https://herrhotzenplotz.de/gcli/releases/gcli-1.1.0/gcli-1.1.0.tar.xz
Now that you have a link, you can download it, extract it, compile the code and install it:
$ mkdir ~/build
$ cd ~/build
$ curl -4LO https://herrhotzenplotz.de/gcli/releases/gcli-1.1.0/gcli-1.1.0.tar.xz
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 342k 100 342k 0 0 2739k 0 --:--:-- --:--:-- --:--:-- 2736k
$ ls
gcli-1.1.0.tar.xz
$
Install the dependencies for building gcli:
e.g. on Debian systems:
# apt install libcurl4-openssl-dev pkgconf build-essential
or on MSYS2:
$ pacman -S libcurl-devel pkgconf
Extract the tarball:
$ tar xf gcli-1.1.0.tar.xz
$ cd gcli-1.1.0
Configure, build and install gcli:
$ ./configure
...
$ make
...
$ make install
Check that the shell finds gcli:
$ which gcli
/usr/local/bin/gcli
$
$ gcli version
gcli 1.1.0 (amd64-unknown-freebsd13.2)
Using libcurl/8.1.2 OpenSSL/1.1.1t zlib/1.2.13 libpsl/0.21.2 (+libidn2/2.3.4) libssh2/1.11.0 nghttp2/1.53.0
Using vendored pdjson library
Report bugs at https://gitlab.com/herrhotzenplotz/gcli/.
Copyright 2021, 2022, 2023 Nico Sonack <nsonack@herrhotzenplotz.de> and contributors.
$
Advanced Windows Environment Setup
In case you want to use the installed gcli from outside MSYS2 (e.g. in cmd.exe) you may wish to update
the Path environment variable and add the C:\msys2\usr\bin directory to it. Make sure you have the
library paths set up correctly.
First steps
Listing issues
Let’s start off by listing some issues - here for the curl project which is hosted on GitHub under
curl/curl. To list issues for it one would run:
$ gcli -t github issues -o curl -r curl
You will see the list of the 30 most recent open issue tickets. The command above does the following:
• invoke gcli
• as a global option we switch it into GitHub-Mode
• invoke the issues subcommand
• operate on the repository owner curl (-o curl)
• operate on the repository curl (-r curl)
Note that the -t github option goes before the issues subcommand because it is a global option for gcli
that affects how all the following things like subcommands operate.
However, now I also want to see closed issues:
$ gcli -t github issues -o curl -r curl -a
The -a option will disregard the status of the issue.
Oh and the screen is a bit cluttered by all these tickets - let’s only fetch the first 10 issues:
$ gcli -t github issues -o curl -r curl -n10
Searching for issues
Before reporting a bug or looking for solutions to a problem that you found in a program you may want to
search for issues.
Let’s search for avast in curl/curl:
$ gcli -t github issues -o curl -r curl -a avast
NUMBER NOTES STATE TITLE
11383 9 open Issue with FileZilla server (GnuTLS) and close_notify
10551 7 closed Unable to use curl 7.87 for SSL connections on Windows 10 Pro
8848 2 closed CURL SSL certificate problem when AVAST HTTPS scanning enabled
$
As you can see searching for something is just a matter of appending keywords to the issues subcommand.
You can specify any amount of search terms - they will all be used in the query. Again, -a ignores the
status of the issue such that we also see closed tickets.
Examining issues
As of now we only produced lists of issues. However, we may also want to look at the details of an issue
such as:
• the original post
• labels
• comments
• assignees of the issue (that is someone who is working on the bug)
Let’s get a good summary of issue #11268 in the curl project:
$ gcli -t github issues -o curl -r curl -i 11268 all
As you can see most of the options are the same, however now we tell gcli with the -i 11268 option that
we want to work with a single issue. Then we tell gcli what actions to perform on the issue. Another
important action is comments. Guess what it does:
$ gcli -t github issues -o curl -r curl -i 11268 comments
I know a person that likes to post long verbose traces. Let’s search for an issue authored by them on the
OpenSSL GitHub page:
$ gcli -t github issues -o openssl -r openssl -A blastwave -a
NUMBER STATE TITLE
20379 open test "80-test_ssl_new.t" fails on Solaris 10 SPARCv9
10547 open Strict C90 CFLAGS results in sha.h:91 ISO C90 does not support long long
8048 closed OPENSSL_strnlen SIGSEGV in o_str.c line 76
$
The -A option lets you filter for specific authors.
Let’s look at the issue state of #10547:
$ gcli -t github issues -o openssl -r openssl -i 10547 status
NAME : 10547
TITLE : Strict C90 CFLAGS results in sha.h:91 ISO C90 does not support long long
CREATED : 2019-12-01T04:35:23Z
AUTHOR : blastwave
STATE : open
COMMENTS : 9
LOCKED : no
LABELS : triaged: bug
ASSIGNEES : none
$
That’s nine comments - let’s read the original post and the comments in our favourite pager less:
$ gcli -t github issues -o openssl -r openssl -i 10547 op comments | less
As you can see gcli will accept multiple actions for an issue and executes them sequentially.
How to find documentation
When using gcli one may not always remember all the options and flags for every subcommand. gcli has lots
of integrated help to guide you through its commands.
Subcommand help
You can list all available options for the issues subcommand by doing:
$ gcli issues --help
With your current knowledge you can also explore the gcli pulls subcommand.
General usage
Run the following command:
$ gcli --help
usage: gcli [options] subcommand
OPTIONS:
-a account Use the configured account instead of inferring it
-r remote Infer account from the given git remote
-t type Force the account type:
- github (default: github.com)
- gitlab (default: gitlab.com)
- gitea (default: codeberg.org)
-c Force colour and text formatting.
-q Be quiet. (Not implemented yet)
-v Be verbose.
SUBCOMMANDS:
ci Github CI status info
comment Comment under issues and PRs
config Configure forges
forks Create, delete and list repository forks
gists Create, fetch and list Github Gists
issues Manage issues
labels Manage issue and PR labels
milestones Milestone handling
pipelines Gitlab CI management
pulls Create, view and manage PRs
releases Manage releases of repositories
repos Remote Repository management
snippets Fetch and list Gitlab snippets
status General user status and notifications
api Fetch plain JSON info from an API (for debugging purposes)
version Print version
gcli 1.2.0 (amd64-unknown-freebsd13.2)
Using libcurl/8.1.2 OpenSSL/1.1.1t zlib/1.2.13 libpsl/0.21.2 (+libidn2/2.3.4) libssh2/1.11.0 nghttp2/1.53.0
Using vendored pdjson library
Report bugs at https://gitlab.com/herrhotzenplotz/gcli/.
Copyright 2021, 2022, 2023 Nico Sonack <nsonack@herrhotzenplotz.de> and contributors.
This gives you an overview over all the available subcommands. Each subcommand in turn allows you to get
its usage by supplying the --help option to it.
Manual pages
Furthermore I recommend reading into the manual page gcli-issues(1) and gcli-pulls(1):
$ man gcli-issues
$ man gcli-pulls
Setting up gcli for use with an account
Creating issues on GitHub requires an account which we need to generate an authentication token for gcli.
If you want to test this with a different forge than GitHub look at the tutorial for other forges.
Log into your GitHub account and click on your account icon in the top right corner. Then choose the
Settings option. Scroll down and choose Developer settings on the bottom of the left column. Under
Personal access tokens choose Tokens (classic).
Click on Generate new token (classic).
Set a useful name such as gcli in the Note field, set the expiration to No expiration and allow the
following Scopes:
• repo
• workflow
• admin:public_key
• gist
Then create the token. It’ll be printed in green. Do not share it!
Now we need to tell gcli about this new token. To do this, create a configuration file for gcli - on
Windows you need to do this from the MSYS2 Shell:
$ mkdir -p ${HOME}/.config/gcli
$ vi ${HOME}/.config/gcli/config
Obviously, you can choose any other editor of your choice. Put the following into this file:
defaults {
editor=vi
github-default-account=my-github-account
}
my-github-account {
token=<token-goes-here>
account=<account-name>
forge-type=github
}
Replace the <token-goes-here> with the previously generated token and the <account> with your account
name.
If you now run
$ gcli -t github repos
you should get a list of your repos. If not, check again that you did all the steps above correctly.
Creating an issue
Note: This assumes you have configured gcli with an account for GitHub already.
Preparation
For this case I have a playground repository that you may as well use for testing with gcli. It is
available at herrhotzenplotz/ghcli-playground.
To see a list of issues, we can run:
$ gcli -t github issues -o herrhotzenplotz -r ghcli-playground -a
NUMBER NOTES STATE TITLE
13 0 open yet another issue
12 0 closed wat
11 0 closed blaaaaaaaaaaaaaaaaaaaah
10 0 closed "this is the quoted" issue title? anyone?"
9 0 closed test
8 0 closed foobar
7 0 closed foobar
5 0 closed test2
4 0 closed test
$
Invoke gcli
Let’s create a bug report where we complain about things not working:
$ gcli -t github issues create -o herrhotzenplotz -r ghcli-playground \
"Bug: Doesn't work on my machine"
The message “Bug: doesn’t work on my machine” is the title of the issue.
Original Post
You will see the default editor come up and instruct you to type in a message. This message is the
“original post” or the body of the issue ticket that you’re about to submit. You can use Markdown Syntax:
I tried building this code on my machine but unfortunately it errors
out with the following message:
```console
$ make love
make: don't know how to make love. Stop
make: stopped in /tmp/wat
$
```
What am I doing wrong?
! ISSUE TITLE : Bug: Doesn't work on my machine
! Enter issue description above.
! All lines starting with '!' will be discarded.
Submit the issue
After you save and exit the editor gcli gives you a chance to check back and finally submit the issue.
Type ‘y’ and hit enter.
You can check back if the issue was created and also view details about it as you learned earlier.
Commenting
Discussions on GitHub and the like are done through comments. You can comment on issues and pull
requests.
Reviewing a discussion
Say you were looking at an issue in curl/curl:
$ gcli issues -o curl -r curl -i 11461 comments
Create the comment
And now you wish to respond to this thread:
$ gcli comment -o curl -r curl -i 11461
This will now open the editor and lets you type in your message. After saving and exiting gcli will ask
you to confirm. Type ‘y’ and hit enter:
$ gcli -t github comment -o curl -r curl -i 11461
You will be commenting the following in curl/curl #11461:
Is this okay? [yN] y
$
Commenting on pull requests
When you want to comment under a pull request use the -p flag instead of the -i flag to indicate the PR
number.
Creating a pull request
Creating a pull request with gcli is usually as simple as running
$ gcli pulls create
Preparation
Suppose you have a git repository forked and cloned:
$ git clone git@github.com:contour-terminal/contour
$ cd contour
$ gcli forks create --into herrhotzenplotz
Then you do some work on whatever feature you’re planning to submit:
$ git checkout -b my-amazing-feature
<hackhackhack>
$ git add -p
$ git commit
Push your changes
You then push your changes to your fork:
$ git push origin my-amazing-feature
Create the pull request
Now you can run the command to create the pull request:
$ gcli pulls create
From (owner:branch) [herrhotzenplotz:my-amazing-feature]:
Owner [contour-terminal]:
Repository [contour]:
To Branch [master]:
Title: Add new amazing feature
Enable automerge? [yN]:
Most of the defaults you should be able to simply accept. This assumes that you have the source branch
checked out locally and remotes are configured appropriately.
Otherwise you can just change the defaults by entering the correct values.
Enter original post
After you entered all the meta data of the pull request gcli will drop you into your editor and lets you
enter a message for the pull request.
Submit
After you saved and exit type y and hit enter to submit the pull request.
Other forges and bugtrackers
gcli is capable of not only interacting with Github. It also currently supports:
• GitLab
• Gitea
• Bugzilla
Bugzilla
Notes
Bugzilla is commonly used as a bug tracker in various large open-source projects such as FreeBSD, the
Linux Kernel, Mozilla and Gentoo.
Searching
Suppose you want to search for bug reports containing sparc in the Gentoo Bugzilla.
In this case you need to configure an account that points at the correct URL in $HOME/.config/gcli/config
by adding:
gentoo {
forge-type=bugzilla
api-base=https://bugs.gentoo.org/
}
Now you can search the Gentoo Bugs:
$ gcli -a gentoo issues sparc
NUMBER NOTES STATE TITLE
924443 0 UNCONFIRMED Add keyword ~sparc for app-misc/fastfetch
924430 0 RESOLVED media-libs/assimp-5.3.1 fails tests on sparc
924215 0 CONFIRMED dev-libs/libbson dev-libs/mongo-c-driver: alpha arm ia64 mips ppc ppc64 s390 sparc keyword req
924191 0 CONFIRMED media-libs/exempi: unaligned access causes dev-python/python-xmp-toolkit-2.0.2 to fails tests on sparc (test_file_to_dict (test.test_core_unit.UtilsTestCase.test_file_to_dict) ... Bus error)
924180 0 CONFIRMED dev-python/psycopg-3.1.17[native-extensions] fails tests on sparc: tests/test_copy_async.py::test_read_rows[asyncio-names-1] Fatal Python error: Bus error
924031 0 IN_PROGRESS sys-apps/bfs: ~arm ~arm64 ~ppc ~ppc64 ~sparc keywording
923968 0 CONFIRMED dev-python/pyarrow-15.0.0 fails to configure on sparc: CMake Error at cmake_modules/SetupCxxFlags.cmake:42 (message): Unknown system processor
921245 0 CONFIRMED media-video/rav1e-0.6.6 fails to compile on sparc: Assertion `DT.dominates(RHead, LHead) && "No dominance between recurrences used by one SCEV?"' failed.
920956 0 CONFIRMED dev-python/pygame-2.5.2: pygame.tests.font_test SIGBUS on sparc
920737 0 CONFIRMED sparc64-solaris Prefix no longer supported
<snip>
Issue details
Furthermore we can look at single issues:
$ gcli -a gentoo issues -i 920737 all comments
NUMBER : 920737
TITLE : sparc64-solaris Prefix no longer supported
CREATED : 2023-12-26T19:20:58Z
PRODUCT : Gentoo Linux
COMPONENT : Profiles
AUTHOR : Tom Williams
STATE : CONFIRMED
LABELS : none
ASSIGNEES : prefix
ORIGINAL POST
Resurrecting a Prefix install on Solaris 11.4 SPARC. It was working rather well
for me; after a hiatus I had hoped to use it again but my first emerge --sync
has removed the profile needed to merge any updates or new packages.
I note commit 8e006b67e06a19fae10c6059c7fc5ede88834601 in May 2023 removed the
profile and keywording for prefixed installs.
There is no associated comment. There doesn't seem to be a bug report in regards
to the change (I'm quite sure almost nobody uses it, so probably fair enough)
Any easy way to restore the profile for now? Eventually Solaris/SPARC and thus
Prefix will be gone anyway, but useful for now.
Thanks for your continued efforts.
AUTHOR : sam
DATE : 2023-12-26T19:21:33Z
I think at the very least, when removing Prefix support in future, a 'deprecated'
file should be added to the relevant profiles asking if anyone is using
it to step forward.
AUTHOR : grobian
DATE : 2023-12-26T22:58:12Z
Solaris 11.4 itself is a problem. I doubt you ever had it "working".
AUTHOR : grobian
DATE : 2023-12-26T22:59:57Z
Linux sparc team is not relevant here
$
GitLab
Configuring an account for use with a token
First you need to generate a token:
1. Click on your avatar in the top left corner
2. Choose Preferences in the popup menu
3. Select Access tokens in the preference menu
4. Click the Add new token button
5. Choose some reasonable values
• The token name can be your hostname e.g. gcli $(hostname)
• Clear the expiration date. It will be defaulted to some high value by GitLab.
• Select the api scope
Now click Create personal access token. Save this token - do not share it with anyone else.
You can now update your gcli config in $HOME/.config/gcli/config:
defaults {
gitlab-default-account=gitlab-com
...
}
gitlab-com {
account=<your-username-at-gitlab>
token=<the-token-you-just-created>
forge-type=gitlab
}
After that you should be able to run the following command:
$ gcli -t gitlab issues -o herrhotzenplotz -r gcli
If this process errors out check the above steps. If you believe this is a bug, please report it at our
issue tracker!
Gitea
The steps here are roughly the same as with GitLab.
To generate a token:
1. Click your avatar in the top-right corner
2. Choose Settings in the popup menu
3. Select Applications in the menu on the left
4. Under Generate new token enter a reasonable token name
5. Click the Generate token button
6. Save the token - do not share it with anyone else.
You can now update your gcli config file in $HOME/.config/gcli/config:
defaults {
gitea-default-account=codeberg-org
...
}
codeberg-org {
account=<your-username-at-gitea>
token=<the-token-you-just-created>
forge-type=gitea
api-base=https://codeberg.org/api/v1
}
The example here uses Codeberg. Update these fields as needed for your own use case.
04-Oct-2025 gcli-tutorial(1)