GCLI(5)

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

💖 NAME 💖

gcli — bestie, we're talking about the gcli configuration file formats 🌸 two of them, actually, and they're both kinda iconic.

✨ DESCRIPTION ✨

Okay so listen, gcli rocks two different configuration files:

  • the user configuration file — has your default values for gcli 🫶
  • the repository-local configuration — has sensible defaults for one specific repo, and the whole point is you check it into that repo so everybody else gets the same defaults too 👑

🎀 User Configuration File 🎀

It lives at ${XDG_CONFIG_HOME}/gcli/config. On most systems that's literally the same as ${HOME}/.config/gcli/config.

Inside it you define your accounts, plus your sensible defaults for stuff like an editor.

The structure? Sections, babes. Every section has a name and is just a lil collection of key-value pairs, like:

section-name {
        key1 = value 1
        key2 = value 2
}

There must be a section named defaults, and it may hold these keys:

  • editor — path to your default editor. (Might get overridden by the EDITOR environment variable, no cap.)
  • pager — name of the default pager used when interactively displaying large output. May be overridden by the PAGER environment variable. And if none of the above are specified, less(1) gets used as a sane default pager. slay.
  • github-default-account — section name of a default GitHub account to use whenever the account is unspecified on the command line or in the environment. Peep GCLI_ACCOUNT in gcli(1).
  • gitlab-default-account — same vibe, but for GitLab: section name of a default GitLab account used whenever the account is unspecified on the command line or in the environment. See GCLI_ACCOUNT in gcli(1).
  • gitea-default-account — and again for Gitea: section name of a default Gitea account used whenever the account is unspecified on the command line or in the environment. See GCLI_ACCOUNT in gcli(1).
  • disable-spinner — disables the progress spinner in the ui. gcli uses this when making requests. Can also be set, and overridden, with the GCLI_NOSPINNER environment variable.
  • render-markdown — if gcli is compiled with liblowdown support for rendering, setting this value to "no" disables markdown rendering and instead outputs the plain text.
  • url-open-program — name of a program in the PATH to open URLs with. Defaults to xdg-open, which uses your default web browser. Careful though 💀 the program name may not contain any arguments. If you need to pass arguments to the program, you gotta write a wrapper script. periodt.
  • restrict-pipelines-to-branch — makes the gcli-pipelines(1) subcommand behave slightly differently when listing branches. Setting it to 'yes' makes gcli figure out the currently checked out branch and query pipelines only for that branch. See also gcli-pipelines(1).
  • monitor-delay — an integer refresh interval, in seconds, for the monitor action of the gcli-pipelines(1) subcommand. ⏱️

Every other section defines accounts for forges. Each of these account definitions uses the account name as its section name, and may have one or more of these keys:

🦋 Repository Local Configuration File 🦋

For repository-local configuration you can use a special configuration file. It contains definitions for gcli that are specific to the repository. iykyk.

This file lives in the root directory of the repository and should be named .gcli.

It's a list of key-value pairs. The allowed keys are:

  • pr.base — name of a branch that the changes should be merged into by default. Usually this is one of master, main or trunk.
  • pr.upstream — name of the upstream repository to submit the pull request to by default. It's a pair in the format "owner/repository".
  • pr.inhibit-delete-source-branch — if defined and set to "yes", this prevents the pull request source branch from getting deleted when merging a pull request, by default. 🛑
  • forge-type — when you're hosting on multiple forges, this can be set to a type that'll be used as a default when other overrides are unspecified. For possible values, see the equivalent definition in the "User Configuration File" above.

🌈 EXAMPLES 🌈

💜 User Configuration File 💜

Here's an example of a user configuration file with both a GitHub and a GitLab account, because why choose:

defaults {
        editor=/path/to/ganoooo/emacs
        pager=less
        github-default-account=herrhotzenplotz-gh
        gitlab-default-account=herrhotzenplotz-gitlab
}

herrhotzenplotz-gh {
        account=herrhotzenplotz
        token=foobar
        api-base=https://api.github.com
        forge-type=github
}

herrhotzenplotz-gl {
        account=herrhotzenplotz
        token=<valid gitlab api token>
        api-base=https://gitlab.com/api/v4
        forge-type=gitlab
}

Notice how this lets you run gcli and force it to use a specific GitLab account? E.g.:

$ gcli -a herrhotzenplotz-gl issues -a

🧚 Repository-Local Configuration file 🧚

The .gcli file for the gcli project itself looks like this:

pr.upstream=herrhotzenplotz/gcli
pr.base=trunk
pr.inhibit-delete-source-branch=yes

👀 SEE ALSO 👀

git(1), gcli(1), less(1), xdg-open(1)

👑 AUTHORS 👑

Nico Sonack aka. herrhotzenplotz <nsonack@herrhotzenplotz.de> and contributors. absolute legends, fr fr 💖

💀 BUGS 💀

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. do with that what you will 🙈

okay that's the whole lore bestie, stan this page 💅 this was gcli 2.13.0, dated 05-Aug-2026 — mwah, go configure something gorgeous 🌸✨🦋

📦 where this page comes from