DOCSEARCHbyAlgolia
Submit Docs

GCLI

repository·trunk·Indexed 41 days ago

https://github.com/herrhotzenplotz/gcli

A portable command-line interface tool providing a unified way to interact with Git hosting services including GitHub, GitLab, Gitea, and Forgejo, as well as Bugzilla. GCLI allows users to manage issues, merge requests, CI, releases, and milestones across different forges using a consistent syntax.

Tokens
35.9K
Snippets
153
Records
199
Agent score
46%

What's inside GCLI

  1. Overview of GCLI features and supported platforms

    trunk

    GCLI is a portable CLI tool designed to provide a unified interface for interacting with multiple forge and issue tracking services.

    Supported Services:

    • GitHub
    • GitLab
    • Gitea
    • Forgejo
    • Bugzilla

    Key Capabilities:

    • Manage issues, merge requests, continuous integration (CI), releases, and milestones.
    • Integration with version control systems: Git and GoT.
    • Suitable for both interactive use and automated scripting.
    • Built-in help and manual pages (start with gcli(1)).

  2. Add support for new forges

    trunk

    To add a new forge (data source), the primary entry point is include/gcli/forges.h, which contains the dispatch table for fetching data.

    Implementation Steps

    1. Modify the dispatch table in include/gcli/forges.h.
    2. Use gcli_forge() to retrieve a pointer to the current dispatch table.
    3. Implement routines for automagic detection and command-line overrides.

    Note: Avoid calling gcli_forge() directly when adding a new forge type; instead, use the available frontend functions that handle dispatching for the caller.

  3. Configure GitLab with a Personal Access Token

    trunk

    To interact with GitLab, you must generate a Personal Access Token via the GitLab web interface with the api scope enabled. Once generated, add a configuration block to $HOME/.config/gcli/config.

    Configuration

    You can set a default GitLab account in the defaults block using gitlab-default-account.

    Usage

    You can access issues using the -t flag for the account name, or use the forge path shorthand (e.g., gl:owner/repo or account-name:owner/repo).

    defaults {
    gitlab-default-account=gitlab-com
}

gitlab-com {
    account=<your-username-at-gitlab>
    token=<the-token-you-just-created>
    forge-type=gitlab
}
    # Using account name
$ gcli -t gitlab issues -o herrhotzenplotz -r gcli

# Using forge path shorthand
$ gcli issues gl:herrhotzenplotz/gcli
$ gcli issues gitlab-com:herrhotzenplotz/gcli

  4. List issues for a repository

    trunk

    Use the issues subcommand to list recent open issue tickets. You must specify the forge (e.g., GitHub), the owner, and the repository. By default, gcli lists the 30 most recent open issues.

    Options:

    • -t <forge>: Global option to set the forge (e.g., github). This must be placed before the subcommand.
    • -o <owner>: The repository owner.
    • -r <repo>: The repository name.
    • -a: Include closed issues in the list (disregard status).
    • -n<number>: Limit the number of issues returned (e.g., -n10).

    Shorthand Syntax: Instead of using -t, -o, and -r separately, you can use a single argument in the format forge:owner/repo (e.g., gh:curl/curl). Supported prefixes include:

    • gh: for GitHub
    • gl: for GitLab
    • cb: for Codeberg
    # Explicit flags
gcli -t github issues -o curl -r curl

# Including closed issues and limiting to 10 results
gcli -t github issues -o curl -r curl -a -n10

# Using shorthand syntax
gcli issues gh:curl/curl -a -n10

  5. Compile GCLI from source

    trunk

    If a pre-compiled package is not available for your OS, you can build GCLI from source.

    1. Install Build Dependencies

    Before compiling, ensure you have the necessary development libraries installed:

    • Debian-based systems: apt install libcurl4-openssl-dev pkgconf build-essential
    • MSYS2: pacman -S libcurl-devel pkgconf

    2. Download and Extract

    Download the latest release tarball from https://herrhotzenplotz.de/gcli/releases, extract it, and enter the directory.

    3. Build and Install

    Run the standard configure, make, and install sequence:

    $ ./configure
$ make
$ make install

    4. Verify Installation

    Confirm the installation by checking the binary location and version:

    $ which gcli
$ gcli version
    # Example build workflow for version 1.1.0
$ mkdir ~/build
$ cd ~/build
$ curl -4LO https://herrhotzenplotz.de/gcli/releases/gcli-1.1.0/gcli-1.1.0.tar.xz
$ tar xf gcli-1.1.0.tar.xz
$ cd gcli-1.1.0
$ ./configure
$ make
$ make install

  6. Search for issues by keywords

    trunk

    To search for specific terms within issues, append the search keywords to the issues subcommand. You can provide multiple keywords, which will all be used in the query. Use the -a flag to include closed issues in your search results.

    # Search for 'avast' in curl/curl including closed issues
gcli -t github issues -o curl -r curl -a avast

  7. Generate a GitHub Personal Access Token for gcli

    trunk

    To allow gcli to create issues and interact with your repositories, you must generate a GitHub Personal Access Token (classic) with specific scopes.

    1. Log into GitHub and navigate to Settings > Developer settings > Personal access tokens > Tokens (classic).
    2. Click Generate new token (classic).
    3. Set a note (e.g., gcli) and set expiration to No expiration.
    4. Select the following required Scopes:
      • repo
      • workflow
      • admin:public_key
      • gist
    5. Generate and copy the token immediately.

  8. Examine specific issue details and actions

    trunk

    To inspect a single issue, use the -i <issue_number> option. Once an issue is targeted, you can specify one or more actions to perform on it. Actions are executed sequentially.

    Common Actions:

    • all: Provides a summary of the issue (original post, labels, assignees, etc.).
    • comments: Retrieves the comments associated with the issue.
    • status: Shows the issue state (name, title, creation date, author, state, etc.).

    Filtering:

    • -A <author>: Filter issues by a specific author.
    # Get a full summary of issue #11268
gcli -t github issues -o curl -r curl -i 11268 all

# Get only the comments for issue #11268
gcli -t github issues -o curl -r curl -i 11268 comments

# Check the status of issue #10547
gcli -t github issues -o openssl -r openssl -i 10547 status

# Search for issues authored by 'blastwave' including closed ones
gcli -t github issues -o openssl -r openssl -A blastwave -a

# Pipe multiple actions to a pager
gcli -t github issues -o openssl -r openssl -i 10547 op comments | less

  11. Build GCLI from source

    trunk

    To build GCLI from source, use the provided ./configure and make workflow. You can optionally specify a --prefix for the installation directory or use DESTDIR during the install phase.

    By default, the installation destination is $DESTDIR/$PREFIX/....

    $ ./configure [--prefix=/usr/local]
$ make
# make [DESTDIR=/] install

  12. Create a GitHub issue with gcli

    trunk

    To create a new issue on GitHub using gcli, use the issues create command. You must specify the target type (-t github), the organization or user (-o <owner>), and the repository (-r <repo>). The first argument provided after the repository flag is treated as the issue title.

    After running the command, gcli will open your default system editor. The text you write in the editor becomes the body (original post) of the issue. You can use Markdown syntax in the body.

    Note: Lines starting with ! in the editor are treated as instructions/metadata and will be discarded from the final issue body.

    Once you save and exit the editor, gcli will prompt you to confirm the submission. Type y and press Enter to finalize the creation.

    $ gcli -t github issues create -o herrhotzenplotz -r ghcli-playground "Bug: Doesn't work on my machine"