Ubuntu Manpage: gcli — interact with git forges without using a web-browser

NAME

       gcli — interact with git forges without using a web-browser

SYNOPSIS

       gcli [overrides] subcommand [options]

DESCRIPTION

       gcli  can  be  used to interact with git(1) forges like GitHub, GitLab and Gitea from the command line in
       order to make many tasks like managing issues and pull requests easier.

       If you're looking for a guided tutorial either go to https://herrhotzenplotz.de/gcli/tutorial or read the
       offline version gcli-tutorial(1).

       Calls to gcli usually consist of either only the subcommand to list requested data or the subcommand plus
       further subcommands or options to perform various tasks. Some commands may also take an item  to  operate
       on  and  accept multiple actions that will be performed on the item (e.g. PRs may be summarised, comments
       fetched and a diff printed all in one command).

       The default behaviour of gcli can be overridden to accommodate more nuanced use cases.  Manual  overrides
       must be passed before subcommands and their options.

SUBCOMMANDS

       Most of these subcommands are documented in dedicated man pages.

       issues      Issues in repositories. See gcli-issues(1).

       pulls       Pull Requests on repositories. See gcli-pulls(1).

       labels      Manage labels for issues and pull/merge requests on repositories. See gcli-labels(1).

       forks       Forking repositories. See gcli-forks(1).

       gists       GitHub Gists are like paste bins to where you can dump code snippets etc. See gcli-gists(1).

       snippets    Support for GitLab snippets. See gcli-snippets(1).

       repos       Manage your own or other repositories. See gcli-repos(1).

       comment     Submit comments under issues and PRs. See gcli-comment(1).

       status      Print a list of TODOs and/or notifications. See gcli-status(1).

       pipelines   Inspect and manage GitLab Pipelines. See gcli-pipelines(1).

       releases    Create and manage releases. See gcli-releases(1).

       milestones  List and manage milestones. See gcli-milestones(1).

       config      Change  user  settings  for  the  forge.  Allows  you  to e.g. upload or delete ssh keys. See
                   gcli-config(1).

       api         Perform direct queries to the API and dump the JSON response to  stdout.  This  is  primarily
                   intended to assist debugging gcli. See gcli-api(1).

       version     Print version and exit.

OPTIONS

gcli overrides are:

-a, --account override-account
Manually override the default account. override-account must name a config section for an
account in the global config file. See “FILES”.

-r, --remote override-remote
Use override-remote as the remote when trying to infer repository data.

-c, --colours
Ignore NO_COLOR as well as whether the output is not tty and print ANSI escape sequences for
changing text formatting. Default is to output colours unless stdout is not a tty. See isatty(3).
This is useful in combination with modern pagers such as less(1).

--no-spinner
Disable the animated spinner that is displayed when gcli is making network requests. This is
useful inside dumb terminals or in editors such as acme. See also GCLI_NOSPINNER in
“ENVIRONMENT”.

--no-markdown
Disable automatic markdown rendering. This is useful in case improperly formatted markdown is
causing unreadable output or if messages aren't markdown at all. See also GCLI_RENDER_MARKDOWN
in “ENVIRONMENT”.

-q, --quiet
Suppresses most output of gcli.

-v, --verbose
Be very verbose. This means that warnings about missing config files and request steps are
printed to stderr.

-t, --type forge-type
Forcefully override the forge type. Set forge-type to ‘github’, ‘gitlab’ ‘gitea’, or ‘bugzilla’
to connect to the corresponding services.

Common options across almost all of the subcommands are:

-s, --sorted
Reverse the output such that most recent items appear at the bottom.

-n, --count n
Fetch multiple items of data. The default is usually 30 items, but this parameter allows to fetch
more than that. Setting n to -1 will result in all pages being queried and all items being read.
However, be careful with that, since if there is a lot of data to be fetched, it may result in
rate limiting by the GitHub API, aside from the fact that it may also take a considerable amount
of time to process.

-a, --all
Fetch all data, including closed issues and closed/merged PRs.

-y, --yes
Do not ask for confirmation when performing destructive operations or performing submissions.
Always assume yes.

-o, --owner owner
Operate on the given owner (organisation or user). Can only be used in combination with -r.

-r, --repo repo
Operate on the given repository. Can only be used in combination with -o.

-i id Operate on the given numeric identifier.

Other options specific to the context are documented in the respective man pages.

ENVIRONMENT

GIT_EDITOR, VISUAL, EDITOR
If the gcli config file does not name an editor, gcli will search the named environment
variables in this order and use the first that is set as the editor.

XDG_CONFIG_HOME There should be a subdirectory called gcli in the directory this environment variable
points to where gcli will go looking for its configuration file. See “FILES”.

GCLI_ACCOUNT Specifies an account name that should be used instead of an inferred one. The value of
GCLI_ACCOUNT can be overridden again by using -a account-name. This is helpful in cases
where you have multiple accounts of the same forge-type configured and you don't want to
use the default.

NO_COLOR If set to ‘1’, ‘y or’ ‘yes’ (capitalisation ignored) this will suppress output of ANSI
colour escape sequences. See “OPTIONS” (--colours).

GCLI_NOSPINNER If set to ‘1’, ‘y or’ ‘yes’ (capitalisation ignored) this will disable the animated
spinner when gcli is making requests. See “OPTIONS” (--disable-spinner)

GCLI_RENDER_MARKDOWN
If this is set to ‘0’, ‘n or’ ‘no’ (capitalisation ignored) this will disable markdown
rendering in gcli's output. See “OPTIONS” (--no-markdown).

FILES

       ${XDG_CONFIG_HOME}/gcli/config  The  user configuration file for gcli. It contains account definitions as
                                       well as sensible default values. See gcli(5).

       .gcli                           A repo-specific config file intended to be committed  into  the  repo  so
                                       that  users  don't  have  to  manually specify all the options like --in,
                                       --from, --base -etc. when creating pull requests. See gcli(5) for details
                                       about this file.

EXAMPLES

       List recently opened issues in the current upstream repository:

             $ gcli issues

       Merge upstream PR #22:

             $ gcli pulls -p 22 merge

       Get a summary and comments of upstream PR #22:

             $ gcli pulls -p 22 summary comments

       Establish a connection to GitHub  and  print  the  last  10  pull  requests  in  contour-terminal/contour
       regardless of their state.

             $ gcli -t github pulls -o contour-terminal -r contour -a -n10

       This can be useful if neither your config file nor the directory you're working from contain the relevant
       forge and repository information.

HISTORY

       The idea for gcli appeared during a long rant on IRC where the issue with the official  tool  written  by
       GitHub  became  clear to be the manual dialling and DNS resolving by the Go runtime, circumventing almost
       the entirety of the IP and DNS services of the operating system and leaking  sensitive  information  when
       using Tor.

       Implementation started in October 2021 with the goal of having a decent, sufficiently portable and secure
       version of a cli utility to interact with the GitHub world without using the inconvenient web interface.

       Later, support for GitLab and Gitea (Codeberg) were added.

AUTHORS

       Nico Sonack aka. herrhotzenplotz <nsonack@herrhotzenplotz.de> and contributors.

CAVEATS

       Not  all  features  that are available from the web version are available in gcli.  However, it is a non-
       goal of the project to provide all this functionality.

BUGS

       There is an undocumented ci subcommand available for GitHub CI services. The subcommand  is  undocumented
       as it is not well tested and likely subject to changes.

       Please report bugs via E-Mail to https://lists.sr.ht/~herrhotzenplotz/gcli-discuss.

       Alternatively  you  can  report  them on any of the forges linked at https://sr.ht/~herrhotzenplotz/gcli.
       However, the preferred and quickest method is to use the mailing list.

       You may also report an issue like so:

             $ gcli -a some-gitlab-account \
                     issues create \
                     -o herrhotzenplotz -r gcli \
                     "BUG : ..."

gcli 2.9.1                                         04-Oct-2025                                           GCLI(1)