User Configuration File

The user configuration file is located in ${XDG_CONFIG_HOME}/gcli/config. On most systems this equal to ${HOME}/.config/gcli/config.

The user configuration file contains definitions for accounts as well as sensible default values for things like an editor.

The file is structured in sections, each section has a name and consists of a collection of key-value pairs. E.g.:

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

There must be a section named “defaults” which may contain the following keys:

editor

Path to a default editor. This might be overridden by the environment variable EDITOR.

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. See GCLI_ACCOUNT in gcli(1).

gitlab-default-account

Section name of a default GitLab account to use whenever the account is unspecified on the command line or in the environment. See GCLI_ACCOUNT in gcli(1).

gitea-default-account

Section name of a default Gitea account to use whenever the account is unspecified on the command line or in the environment. See GCLI_ACCOUNT in gcli(1).

All other sections define accounts for forges. Each of these account definitions have the account name as their section name and may have one or more of the following keys defined:

forge-type

The type of the forge. May be one of:

• github
• gitlab
• gitea

api-base

(optional) Used to override the API base URL of the forge. This is useful for self-hosted instances. Depending on the “forge-type” the default values are:

forge-type	default value
github	https://api.github.com
gitlab	https://gitlab.com/api/v4
gitea	https://codeberg.org/api/v1

account

(optional) The username used to authenticate at the API.

token

(optional) A generated application token to use with this account. TODO: Document for each forge how to generate these.

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.

The Repository-local configuration file is located in the root directory of the repository and should be named .gcli.

It contains a list of key-value pairs. 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. This is a pair of the format “owner/repository”.

pr.inhibit-delete-source-branch

If defined and set to “yes” this will prevent the pull request source branch to get deleted when merging a pull request by default.

forge-type

When hosting on multiple forges this can be set to a type that will be used as a default when other overrides are unspecified. For possible values see the equivalent definition in User Configuration File.

User Configuration File

An example for the user configuration file consisting of both a Github and a Gitlab account:

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

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

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

Notice that this allows you to 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