.Dd @PACKAGE_DATE@
.Dt GCLI 1
.Os @PACKAGE_STRING@
.Sh NAME
.Nm gcli
.Nd interact with git forges without using a web-browser
.Sh SYNOPSIS
.Pp
.Nm
.Op overrides
.Cm subcommand
.Op options
.Sh DESCRIPTION
.Nm
can be used to interact with
.Xr 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.
.Pp
Calls to
.Nm
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).
.Pp
The default behaviour of
.Nm
can be overridden to accommodate more nuanced use cases. Manual
overrides must be passed before subcommands and their options.
.Sh SUBCOMMANDS
Most of these subcommands are documented in dedicated man pages.
.Bl -tag -width milestones
.It Cm issues
Issues in repositories. See
.Xr gcli-issues 1 .
.It Cm pulls
Pull Requests on repositories. See
.Xr gcli-pulls 1 .
.It Cm labels
Manage labels for issues and pull/merge requests on repositories. See
.Xr gcli-labels 1 .
.It Cm forks
Forking repositories. See
.Xr gcli-forks 1 .
.It Cm gists
Github Gists are like paste bins to where you can dump code snippets
etc. See
.Xr gcli-gists 1 .
.It Cm snippets
Support for Gitlab snippets. See
.Xr gcli-snippets 1 .
.It Cm repos
Manage your own or other repositories. See
.Xr gcli-repos 1 .
.It Cm comment
Submit comments under issues and PRs. See
.Xr gcli-comment 1 .
.It Cm status
Print a list of TODOs and/or notifications. See
.Xr gcli-status 1 .
.It Cm pipelines
Inspect and manage Gitlab Pipelines. See
.Xr gcli-pipelines 1 .
.It Cm releases
Create and manage releases. See
.Xr gcli-releases 1 .
.It Cm milestones
List and manage milestones. See
.Xr gcli-milestones 1 .
.It Cm config
Change user settings for the forge. Allows you to e.g. upload or
delete ssh keys. See
.Xr gcli-config 1 .
.It Cm api
Perform direct queries to the API and dump the JSON response to
stdout. This is primarily intended to assist debugging gcli. See
.Xr gcli-api 1 .
.It Cm version
Print version and exit.
.El
.Sh OPTIONS
.Nm
overrides are:
.Bl -tag -width indent
.It Fl a , -account Ar override-account
Manually override the default account.
.Ar override-account
must name a config section for an account in the global config file. See
.Sx FILES .
.It Fl r , -remote Ar override-remote
Use
.Ar override-remote
as the remote when trying to infer repository data.
.It Fl c , -colours
Ignore
.Ev 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
.Xr isatty 3 .
This is useful in combination with modern pagers such as
.Xr less 1 .
.It Fl q , -quiet
Suppresses most output of
.Nm .
.It Fl v , -verbose
Be very verbose. This means that warnings about missing config files
and request steps are printed to stderr.
.It Fl t , -type Ar forge-type
Forcefully override the forge type. Set
.Ar forge-type
to
.Sq github ,
.Sq gitlab
.Sq gitea ,
or
.Sq bugzilla
to connect to the corresponding services.
.El
.Pp
Common options across almost all of the subcommands are:
.Bl -tag -width indent
.It Fl s , -sorted
Reverse the output such that most recent items appear at the bottom.
.It Fl n , -count Ar n
Fetch multiple items of data. The default is usually 30 items, but
this parameter allows to fetch more than that. Setting
.Ar 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.
.It Fl a , -all
Fetch all data, including closed issues and closed/merged PRs.
.It Fl y , -yes
Do not ask for confirmation when performing destructive operations or
performing submissions. Always assume yes.
.It Fl o , -owner Ar owner
Operate on the given owner (organization or user).  Can only be used
in combination with
.Fl r .
.It Fl r , -repo Ar repo
Operate on the given repository.  Can only be used in combination with
.Fl o .
.It Fl i Ar id
Operate on the given numeric identifier.
.El
.Pp
Other options specific to the context are documented in the respective
man pages.
.Sh ENVIRONMENT
.Bl -tag -width XDG_CONFIG_HOME
.It Ev EDITOR
If the gcli config file does not name an editor,
.Nm
may use this editor.
.It Ev XDG_CONFIG_HOME
There should be a subdirectory called gcli in the directory this
environment variable points to where
.Nm
will go looking for its configuration file. See
.Sx FILES .
.It Ev GCLI_ACCOUNT
Specifies an account name that should be used instead of an inferred
one. The value of
.Ev GCLI_ACCOUNT
can be overridden again by using
.Fl a Ar 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.
.It Ev NO_COLOR
If set to
.Sq 1 ,
.Sq y or
.Sq yes
(capitalization ignored) this will suppress output of ANSI colour
escape sequences. See
.Sx OPTIONS
(--colours).
.El
.Sh FILES
.Bl -tag -width ${XDG_CONFIG_HOME}/gcli/config -compact
.It Pa ${XDG_CONFIG_HOME}/gcli/config
The user configuration file for gcli. It contains account definitions
as well as sensible default values. See
.Xr gcli 5 .
.Pp
.It Pa .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
.Fl -in ,
.Fl -from ,
.Fl -base etc.
when creating pull requests. See
.Xr gcli 5 for details about this file.
.Pp
.El
.Sh EXAMPLES
List recently opened issues in the current upstream repository:
.Bd -literal -offset indent
$ gcli issues
.Ed
.Pp
Merge upstream PR #22:
.Bd -literal -offset indent
$ gcli pulls -p 22 merge
.Ed
.Pp
Get a summary and comments of upstream PR #22:
.Bd -literal -offset indent
$ gcli pulls -p 22 summary comments
.Ed
.Pp
Establish a connection to github and print the last 10 pull requests
in contour-terminal/contour regardless of their state.
.Bd -literal -offset indent
$ gcli -t github pulls -o contour-terminal -r contour -a -n10
.Ed
.Pp
This can be useful if neither your config file nor the directory you're
working from contain the relevant forge and repository information.
.Sh SEE ALSO
.Xr git 1 ,
.Xr gcli-issues 1 ,
.Xr gcli-pulls 1 ,
.Xr gcli-labels 1 ,
.Xr gcli-comment 1 ,
.Xr gcli-review 1 ,
.Xr gcli-forks 1 ,
.Xr gcli-repos 1 ,
.Xr gcli-gists 1 ,
.Xr gcli-releases 1 ,
.Xr gcli-comment 1
.Xr gcli-pipelines 1
.Xr gcli-config 1
.Sh HISTORY
The idea for
.Nm
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.
.Pp
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.
.Pp
Later, support for GitLab and Gitea (Codeberg) were added.
.Sh AUTHORS
.An Nico Sonack aka. herrhotzenplotz Aq Mt nsonack@herrhotzenplotz.de
and contributors.
.Sh CAVEATS
Not all features that are available from the web version are available in
.Nm .
However, it is a non-goal of the project to provide all this
functionality.
.Sh BUGS
There is an undocumented
.Cm ci
subcommand available for GitHub CI services. The subcommand is
undocumented as it is not well tested and likely subject to changes.
.Pp
Please report bugs via E-Mail to
.Mt @PACKAGE_BUGREPORT@ .
.Pp
Alternatively you can report them on any of the forges linked at
.Lk @PACKAGE_URL@ .
However, the preferred and quickest method is to use the mailing
list.
.Pp
You may also report an issue like so:
.Bd -literal -offset indent
$ gcli -a some-gitlab-account \\
        issues create \\
        -o herrhotzenplotz -r gcli \\
        "BUG : ..."
.Ed