GCLI(1)

📦
version 2.13.0 · 5 versions
, in nixpkgs unstable, ubuntu stonking

💖 GCLI 💖

okay bestie, welcome to the gcli(1) page — General Commands Manual, section 1, and it's giving iconic. pull up a chair, we're gonna talk about interacting with git forges.

✨ NAME ✨

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

🌸 SYNOPSIS 🌸

gcli [overrides] subcommand [forge-path] [options]

🎀 DESCRIPTION 🎀

so like, gcli is your bestie for talking to git(1) forges — GitHub, GitLab, Gitea, the whole squad — straight from the command line. no browser, no tabs, no doomscrolling. it makes stuff like managing issues and pull requests actually bearable. it's giving productivity era fr fr.

if you want a guided tutorial (and honestly you might, no judgement), either go to https://herrhotzenplotz.de/gcli/tutorial or read the offline version, gcli-tutorial(1). ✨

calls to gcli are usually one of two vibes:

  • just the subcommand, to list the data you asked for, or
  • the subcommand plus further subcommands or options, to actually do stuff.

some commands also take an item to operate on and accept multiple actions that all get performed on that item. like, a PR can be summarised, comments can be fetched, and a diff can be printed — all in one single command. one and done, main character energy 👑

the default behaviour of gcli can be overridden, because sometimes your use case is more nuanced than the defaults are ready for. manual overrides must be passed before subcommands and their options — order matters, bestie, don't come for me.

💅 SUBCOMMANDS 💅

most of these have their own dedicated man pages, because they're that girl.

  • 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).
  • attachments — Work with Bugzilla attachments. See gcli-attachments(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. shortest queen of the list 💅

🌈 OPTIONS 🌈

the gcli overrides 🫶

  • -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. shhh 🤫
  • -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 🔥

  • -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.
⚠️ bestie be careful with that! 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. 💀 (yes, that's the whole point, proceed with caution)
  • -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 repo. 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. go read them, they're cute too. 🎀

🦋 Forge path shorthand 🦋

Many subcommands accept an optional forge-path argument immediately following the subcommand name and before any flags. When present it overrides the default owner, repository and/or forge selection. The following forms are recognised:

  • gh:owner/repo — Use GitHub and operate on the repository owner/repo.
  • gl:owner/repo — Use GitLab and operate on the repository owner/repo.
  • cb:owner/repo — Use Codeberg and operate on the repository owner/repo.
  • account:owner/repo — Use the named config account and operate on the repository owner/repo. account must be a section name in the user config file. See gcli(5).
  • account — Switch to the named config account while inferring the repository from the git remote as usual. This is useful when multiple accounts of the same forge type are configured. 👑

🌸 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.

List issues in herrhotzenplotz/gcli on GitLab:

$ gcli issues gl:herrhotzenplotz/gcli

List open PRs using a named config account:

$ gcli pulls myaccount:owner/repo

🫶 SEE ALSO 🫶

git(1), gcli-issues(1), gcli-pulls(1), gcli-labels(1), gcli-comment(1), gcli-review(1), gcli-forks(1), gcli-repos(1), gcli-gists(1), gcli-releases(1), gcli-comment(1) gcli-pipelines(1) gcli-config(1)

📜 HISTORY 📜

okay so the lore. 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. 😭 not the Tor leak bestie!!

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. glow up ✨

👑 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. periodt.

🐛 BUGS 🐛 (yes bestie, we have those too)

okay so if you find a bug — and you will, because software is humbling like that — please report it via e-mail to https://lists.sr.ht/~herrhotzenplotz/gcli-discuss. she's on the mailing list and she's listening 💖

alternatively you can drop it on any of the forges linked at https://sr.ht/~herrhotzenplotz/gcli. but ngl, the preferred method is the mailing list, and it's also the quickest one. so like… do that one bestie 🫶

and yes, you can even file the issue with gcli itself, which is honestly iconic of her. main character energy, no cap:

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

that's it, that's the whole vibe: pick your account with -a, tell issues to create, point -o at the owner and -r at the repo, then hand over your title. "BUG : ..." is literally the template they're showing you — go on, fill in the ... with the actual chaos you witnessed 😭💀

lowkey a reminder that a good bug report is a gift, not a chore. include what you did, what you expected, what happened instead. be nice about it. the maintainers are people and they're doing this out of love 🌸

and that's a wrap on GCLI(1), bestie 💅 this gorgeous thing is gcli 2.13.0, dated 05-Aug-2026 — so if you're reading this from the future, hi, hope the bugs got fixed 🦋 go file one, or better yet, go run gcli and have the best time. mwah. 🎀✨

📦 where this page comes from