Abandon the gitlab CLI

[gpocentek]

The CLI is not in a good shape today, compared the rest of the library. Alternatives exist and seem to do a better job.

@max-wittig and I don't use the CLI, and don't have much to improve it so we are considering removing it from the python-gitlab code.

The decision is not made, and we hope to get some feedback from users in this issue.

[carleski]

I'd be a bit sad to see this go. We're just getting ready to launch a GitLab instance on our campus, and for my team, having quick CLI tools to help with some administrative work has the potential to be extremely helpful, as we've already seen with some of our other services like Google and Box. If the CLI is to be removed, could anyone make a suggestion as to a good alternative?

…

On Fri, Feb 22, 2019 at 9:51 AM Gauvain Pocentek ***@***.***> wrote: The CLI is not in a good shape today, compared the rest of the library. Alternatives exist and seem to do a better job. @max-wittig <https://github.com/max-wittig> and I don't use the CLI, and don't have much to improve it so we are considering removing it from the python-gitlab code. The decision is not made, and we hope to get some feedback from users in this issue. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#708>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AjpHj7QsBuDJTl4srbYf3E6oDvzFPsfIks5vQAP1gaJpZM4bJwDk> .

-- *Rob Carleski* ITS Collaboration Services University of Michigan 734.764.2777

[max-wittig]

Like mentioned above, we haven't made a final decision yet. But https://github.com/michaellihs/golab seems to be pretty good.

[xarx00]

I was just about to fill a couple of bugs in the gitlab CLI. They can be fixed easily.

What exactly is meant by "not in a good shape"? Does it mean that the code is so buggy that it is not worth fixing? Or that there are some bugs but no one to fix them? Or that the CLI API is incomplete?

If the CLI is in relatively good shape but some functionalities are missing or do not work because of simple bugs, then I'd vote for fixing them and letting the CLI alive.

I actually found your project a couple of days ago because I was searching for a command-line gitlab client. I like yours, especially because it is written in python which I know (in contrast to ruby or go).

[max-wittig]

Thanks for your opinion on this. The thing about CLI programs is that they are language independent and we're just two people maintaining this library (and neither of use uses the CLI). It would be cool, if we would get more people to help here.

[xarx00]

I was shortly looking at golab docs, and I'm missing such basic functionality like listing groups hierarchy. However, I haven't installed golab yet, so maybe golab shows the group hierarchy in its console output. But the docs for command "golab group ls" do not suggest anything like that.

[gpocentek]

@xarx00 here is a list of bugs if you want to look into fixing the CLI: https://github.com/python-gitlab/python-gitlab/issues?q=is%3Aissue+is%3Aopen+label%3Acli

We can of course help if you have questions :)

Thanks!

[jamesquilty]

I'm afraid I have no capacity to contribute, but I do use the CLI and I'd like to see the functionality preserved if possible. I'd much rather install a single library with a unified conceptual approach than have to install two packages which are based on different languages and, inevitably, different conceptual approaches to the CLI.

[gpocentek]

Hi all,

Not much progress on this in the last 3 months. Here is the status:

• basic CLI stuff works OK
• we have a bunch of open bugs, and some CLI commands don't work at all
• CLI help is not good
• we agreed that we need switch to another CLI lib, argparse is not good enough for what we need
• I had a look at other CLI projects, most (all?) of them are not actively maintained

Today the CLI and lib are tightly linked (plenty of attributes defined in the python classes), and the CLI code uses lib introspection to handle argument parsing. It is painful, and doesn't work well. I think we should keep the lib simple since it works fine this way, and we should move the "complexities" (types, mandatory/option arguments, ...) to the CLI, where it makes more sense.

[max-wittig]

Let's preserve the CLI, even though it might be worse than something like https://github.com/michaellihs/golab, but people still use the python-gitlab CLI a lot.

[chrisoldwood]

I recently stumbled upon this project as I was looking for a tool to help me do some basic GitLab admin from the command line (most notably checking up on runners and seeing job failures).

The fact that there were extensive docs to go hand-in-hand with the API docs gave me a warm feeling. I found the CLI easy to pick up largely because of the docs, although the help for the entire list of resources is a little unwieldy and I see a couple of issues already raised around that. Aside from that it's been pretty easy from using the docs to work out what --scope and --sudo are about. Yes, they could be nicer, e.g. listing the values for --scope but it's not a showstopper for me.

My only real stumbling block with the CLI was the sparsity of the output in the default (legacy) mode. I was confused by the lack of properties on display and spent ages looking into the --fields argument to try and get more data out before finally realising (after trying the JSON output) that that was all there really was to see. I'm not sure what role the legacy output plays but I'm not sure it's a good default or useful. (I'm used to the Format-List and Format-Table outputs in PowerShell for initial exploration and simple summaries.)

Once I had the JSON output it was just a hop, skip, and jump to add some jq and column magic to give me the tabular output I wanted (with the essential attributes). I've now wrapped these one-liners up into some simple bash scripts that anyone can easily consume.

While the library is nice to have as a fallback I do not really know Python and so the CLI is more useful to someone like myself coming from the curl/bash angle. I've found it much easier it explore the API by using gitlab --help | grep --color=always <resource> and then drilling into the specific resources and verbs with --help before turning to the GitLab API docs for the finer details.

I'm just one data point but I thought I'd add my vote for it's usefulness as it stands (#593 notwithstanding 🙂). Thanks again for all your hard work, whatever happens.

Note: I was not even aware of golab until reading this thread. I'm going to try it out as Go is something I'm more au fait with but it looks like I've still got to do the jq dance so I'm not sure what else it'll buy me.

[xarx00]

If you are interested, you may look at my fork https://github.com/xarx00/python-gitlab. I fixed some bugs, improved the outputs and implemented various new functions there. The new functions are mainly related to the correspondence between the remote GitLab and its local copy.

But I had to change the core slightly, so this fork is now incompatible with the original and cannot be merged easily. If there is enough interest, I can make it mergeable, but the behaviour of the CLI changed a little, which might be a problem for the python-gitlab maintainers. You should be aware, however, that I'm not going to maintain an official clone if this fork won't be merged in to the original python-gitlab.

If you're going to test it anyway, you'll need to create a .gitlab file in the root directory of your Gitlab subtree copy. It should look like this:

[global]
default = origin
base_group = BI/ESB
timeout = 5
api_version = 4

[origin]
url = https://gitlab.yourdomain.com
ssl_verify = W:\MyProject\config\ca-bundle.crt
private_token = ZX3252U9D5xTV5DUQUzT

The base_group property must contain the gitlab path for the root folder of the local copy. (The idea is that you have a local copy of a subtree structure of the remote Gitlab repo. It is not necessary that all git repos from this subtree are copied locally.) Use the -c @ command-line parameter to refer to the .gitlab file (if your current directory is within the local tree), or use -h for help. The main new command-group (command-object) is named bulk. So, for example

gitlab -c @ bulk pull --group-path BI/ESB/dev/services
gitlab -c @ bulk status --group-path BI/ESB/dev/services --no-git-errors=true --no-ci-errors=true

Tested on Windows, only.

[bufferoverflow]

@xarx00 Please contribute here if you have some fixes.

[xarx00]

I've already contributed several fixes. The other fixes would require more or less substantial changes in the core. I don't remember the details, as it is already several months since I made last changes. But that was why I forked, because I was unable to make the fixes and improvements backwards compatible.

My aim was to add functionality related to local copy of the remote repository, hence the functionality that is not part of the GitLab REST API. I needed to "bend" some functionality in python-gitlab in order I was able to do that. And, along the way, I did also several fixes and improvements.

[JohnVillalovos]

I know of two active CLI tools out there:

• https://github.com/profclems/glab/
• https://github.com/zaquestion/lab

[nejch]

I think it probably doesn't make sense to abandon the CLI entirely, because it seems no other gitlab CLI client covers nearly as many endpoints, except gitbeaker (which might cover more, not sure). golab hasn't been maintained since 2018, glab is closer to gh and covers only a few project-related endpoints (but has a slick interface), and lab is almost a gitlab wrapper for git (like hub is with github). So it seems there's not much overlap between API wrappers and git client wrappers.

A comparison of core commands below (python-gitlab and gitbeaker also nest a lot more subcommands under the core commands, see also https://python-gitlab.readthedocs.io/en/latest/cli-objects.html). *this table's not fair to gitbeaker, because it nests some commands under core ones and combines project/group resources of the same type.

python-gitlab	gitbeaker	golab	glab
application	application-settings	branches	mr
application-appearance	branches	commits	issue
application-settings	broadcast-messages	deploy-keys	pipeline
audit-event	commit-discussions	environments	release
broadcast-message	commits	gendoc	repo
current-user	container-registry	group	label
current-user-email	deploy-keys	group-members	alias
current-user-gp-gkey	deployments	labels
current-user-key	environments	login
current-user-status	epic-discussions	merge-requests
deploy-key	epic-issues	namespaces
deploy-token	epic-notes	open
dockerfile	epics	personal-access-token
event	events	project
feature	feature-flags	protected-branches
geo-node	freeze-periods	user
gitignore	geo-nodes	version
gitlabciyml	gitlabci-yml-templates	zsh-completion
group	gitignore-templates
group-access-request	group-access-requests
group-audit-event	group-badges
group-badge	group-custom-attributes
group-board	group-deploy-tokens
group-board-list	group-issue-boards
group-cluster	group-labels
group-custom-attribute	group-members
group-deploy-token	group-milestones
group-epic	group-runners
group-epic-issue	group-variables
group-epic-resource-label-event	groups
group-export	issue-award-emojis
group-import	issue-discussions
group-issue	issue-note-award-emojis
group-label	issue-notes
group-member	issues
group-merge-request	issues-statistics
group-milestone	jobs
group-notification-settings	keys
group-package	labels
group-project	license
group-runner	license-templates
group-subgroup	lint
group-variable	markdown
hook	merge-request-approvals
issue	merge-request-award-emojis
l-da-pgroup	merge-request-discussions
license	merge-request-notes
merge-request	merge-requests
namespace	namespaces
notification-settings	notification-settings
pages-domain	packages
personal-access-token	pages-domains
project	pipeline-schedule-variables
project-access-request	pipeline-schedules
project-additional-statistics	pipelines
project-approval	project-access-requests
project-approval-rule	project-badges
project-audit-event	project-custom-attributes
project-badge	project-deploy-tokens
project-board	project-hooks
project-board-list	project-import-export
project-branch	project-issue-boards
project-cluster	project-members
project-commit	project-milestones
project-commit-comment	project-snippet-award-emojis
project-commit-discussion	project-snippet-discussions
project-commit-discussion-note	project-snippet-notes
project-commit-status	project-snippets
project-custom-attribute	project-variables
project-deploy-token	projects
project-deployment	protected-branches
project-environment	protected-tags
project-event	push-rules
project-export	release-links
project-file	releases
project-fork	repositories
project-hook	repository-files
project-import	runners
project-issue	search
project-issue-award-emoji	services
project-issue-discussion	sidekiq-metrics
project-issue-discussion-note	snippets
project-issue-link	system-hooks
project-issue-note	tags
project-issue-note-award-emoji	todos
project-issue-resource-label-event	triggers
project-issue-resource-milestone-event	user-custom-attributes
project-issue-resource-state-event	user-emails
project-issues-statistics	user-gpg-keys
project-job	user-impersonation-tokens
project-key	user-s-s-h-keys
project-label	users
project-member	version
project-merge-request	vulnerability-findings
project-merge-request-approval	wikis
project-merge-request-approval-rule
project-merge-request-award-emoji
project-merge-request-diff
project-merge-request-discussion
project-merge-request-discussion-note
project-merge-request-note
project-merge-request-note-award-emoji
project-merge-request-resource-label-event
project-merge-request-resource-milestone-event
project-merge-request-resource-state-event
project-milestone
project-note
project-notification-settings
project-package
project-package-file
project-pages-domain
project-pipeline
project-pipeline-bridge
project-pipeline-job
project-pipeline-schedule
project-pipeline-schedule-variable
project-pipeline-variable
project-protected-branch
project-protected-tag
project-push-rules
project-registry-repository
project-registry-tag
project-release
project-release-link
project-remote-mirror
project-runner
project-service
project-snippet
project-snippet-award-emoji
project-snippet-discussion
project-snippet-discussion-note
project-snippet-note
project-snippet-note-award-emoji
project-tag
project-trigger
project-user
project-variable
project-wiki
runner
runner-job
snippet
todo
user
user-activities
user-custom-attribute
user-email
user-event
user-gp-gkey
user-impersonation-token
user-key
user-membership
user-project
user-status
variable

However, we just got access to https://pypi.org/project/gitlab/ (see pypi/support#793 (comment)) for more details). Originally, the idea was this solves the confusion with people doing pip install gitlab.

But I had the idea it could be used to split the project into a core API library (this project, which can then focus only on covering API endpoints) and a high-level wrapper providing a CLI and maybe other goodies that people request sometimes, like https://github.com/boto/botocore is a core API library used by aws-cli and boto3.

Then all the custom command building and formatting in the CLI (which is quite painful to maintain for edge cases) can go away in favor of click or similar, without adding any dependencies to python-gitlab. people doing pip install gitlab would then get the CLI but also the core library.

Any thoughts on this? Of course the naming of repos would be a question then :D Just throwing this out here since a lot of the CLI related issues have been open for a while, this might help resolve things.

[profclems]

glab provides the alias and api commands which helps users to write their custom commands.

The api command gives users direct authenticated access to the GitLab API. So as a glab user, I can define aliases for custom commands that are not provided by glab.

For instance, glab currently has no command to manage GitLab packages: delete, upload.

Since these commands are not available yet, you can set an aliases for each of them with the api command. For example:

glab alias set delete-package 'api projects/:id/packages/$1 -X DELETE'

You can then use it as:

glab delete-package 5678

You can have an alias to the api command to upload generic packages

glab alias set upload-package 'api projects/:id/packages/generic/$1 -X PUT --input $2'

With this, you have two arguments with the first and second arguments taking package_name/package_version/file_name and path_to_file respectively

glab upload-package myprog/1.0.0/myprog-w64.zip myprog-w64.zip

[ernstki]

I know of two active CLI tools out there:

* https://github.com/profclems/glab/

* https://github.com/zaquestion/lab

…and as of this writing, neither supports GitLab running on a subdirectory off the root. So the CLI from python-gitlab is key for me. I hope it's able to hang in there. :)