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.

     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 summarized, comments fetched and a diff printed all in one command).

     The default behaviour of gcli can be overriden to accomodate 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).

-q, --quiet
Supresses 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 (organization 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

     EDITOR          If the gcli config file does not name an editor, gcli may use this editor.

     XDG_CONFIG_DIR  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’ (capitalization ignored) this will suppress
                     output of ANSI colour escape sequences. See OPTIONS (--colours).

FILES

     ${XDG_CONFIG_DIR}/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 dialing 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 ~herrhotzenplotz/gcli-discuss@lists.sr.ht.

     Alternatively you can report them on any of the forges linked at
     https://herrhotzenplotz.de/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 : ..."