---
name: "gcli"
section: "1"
platform: "linux"
package: "gcli"
version: "2.3.0-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/gcli"
---

# gcli(1)

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)](/git/1.md) 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 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)](/gcli-issues/1.md).

- **pulls**

  Pull Requests on repositories. See [gcli-pulls(1)](/gcli-pulls/1.md).

- **labels**

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

- **forks**

  Forking repositories. See [gcli-forks(1)](/gcli-forks/1.md).

- **gists**

  Github Gists are like paste bins to where you can dump code snippets etc. See [gcli-gists(1)](/gcli-gists/1.md).

- **snippets**

  Support for Gitlab snippets. See [gcli-snippets(1)](/gcli-snippets/1.md).

- **repos**

  Manage your own or other repositories. See [gcli-repos(1)](/gcli-repos/1.md).

- **comment**

  Submit comments under issues and PRs. See [gcli-comment(1)](/gcli-comment/1.md).

- **status**

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

- **pipelines**

  Inspect and manage Gitlab Pipelines. See [gcli-pipelines(1)](/gcli-pipelines/1.md).

- **releases**

  Create and manage releases. See [gcli-releases(1)](/gcli-releases/1.md).

- **milestones**

  List and manage milestones. See [gcli-milestones(1)](/gcli-milestones/1.md).

- **config**

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

- **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)](/gcli-api/1.md).

- **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)](/isatty/3.md). This is useful in combination with modern pagers such as [less(1)](/less/1.md).

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

## 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/5.md).

- *.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)](/gcli/5.md) 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.

## SEE ALSO

[git(1)](/git/1.md), [gcli-issues(1)](/gcli-issues/1.md), [gcli-pulls(1)](/gcli-pulls/1.md), [gcli-labels(1)](/gcli-labels/1.md), [gcli-comment(1)](/gcli-comment/1.md), gcli-review(1), [gcli-forks(1)](/gcli-forks/1.md), [gcli-repos(1)](/gcli-repos/1.md), [gcli-gists(1)](/gcli-gists/1.md), [gcli-releases(1)](/gcli-releases/1.md), [gcli-comment(1)](/gcli-comment/1.md) [gcli-pipelines(1)](/gcli-pipelines/1.md) [gcli-config(1)](/gcli-config/1.md)

## 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 : ..."
```