qodev-gitlab-cli 0.2.2

Agent-friendly CLI for the GitLab API

qodev-gitlab-cli

Agent-friendly CLI for the GitLab API. Designed for both human and AI-agent workflows, with structured JSON output, consistent flags, and predictable error codes.

Why this CLI?

• Agent-friendly — --json on every command, consistent flags, predictable exit codes
• Built for AI agent workflows — works seamlessly with Claude Code, scripts, and automation pipelines
• How it compares: glab is GitLab's official interactive CLI for humans; qodev-gitlab is optimized for programmatic and agent use

Installation

pip install qodev-gitlab-cli

Or run directly without installing:

uvx qodev-gitlab-cli

Quick Start

# Set your GitLab token
export GITLAB_TOKEN="glpat-xxxxxxxxxxxxxxxxxxxx"

# List open merge requests
$ qodev-gitlab mrs list
!42  Add authentication  opened  feature/auth → main

# Get MR details as JSON (for scripts/agents)
$ qodev-gitlab mrs get 42 --json
{"iid": 42, "title": "Add authentication", "state": "opened", ...}

# List pipelines
$ qodev-gitlab pipelines list
12345  running  main  2m ago

# Get details of a specific issue
$ qodev-gitlab issues get 42

# Create a merge request from the current branch
$ qodev-gitlab mrs create --title "Add new feature"

Commands

Group	Subcommand	Description
projects	list	List projects (--owned for owned only)
	get	Get project details
mrs	list	List merge requests (--state)
	get	Get merge request details
	create	Create a merge request (--title, --source, --target, --description, --labels, --squash)
	update	Update a merge request (--title, --description, --labels, --target)
	merge	Merge a merge request (--squash, --when-pipeline-succeeds)
	close	Close a merge request
	discussions	List discussions on a merge request
	changes	Show diff for a merge request
	commits	List commits in a merge request
	approvals	Show approval status
	comment	Comment on a merge request (--body)
	pipelines	List pipelines for a merge request
pipelines	list	List pipelines (--ref, --limit)
	get	Get pipeline details
	jobs	List jobs for a pipeline
	wait	Wait for a pipeline to complete (--timeout, --interval)
jobs	get	Get job details
	log	Get job log output
	retry	Retry a failed job
issues	list	List issues (--state, --labels, --milestone)
	get	Get issue details
	create	Create an issue (--title, --description, --labels)
	update	Update an issue (--title, --description, --labels)
	close	Close an issue
	comment	Comment on an issue (--body)
	notes	List comments/notes on an issue
releases	list	List releases
	get	Get release details by tag
	create	Create a release (--tag, --name, --description, --ref)
variables	list	List CI/CD variables (values hidden)
	get	Get a CI/CD variable
	set	Set (create or update) a CI/CD variable (--protected, --masked)

Configuration

Authentication

Set the GITLAB_TOKEN environment variable, or pass --token on each invocation:

export GITLAB_TOKEN="glpat-xxxxxxxxxxxxxxxxxxxx"

GitLab Instance

By default the CLI targets https://gitlab.com. Override with the GITLAB_URL environment variable or the --url flag:

export GITLAB_URL="https://gitlab.example.com"

Global Options

Flag	Description	Default
--json	Output as JSON (for scripting / agents)	false
--project, -p	Project ID or path	auto-detected from git remote
--limit	Results per page	25
--page	Page number	1
--token	GitLab token (overrides GITLAB_TOKEN)
--url	GitLab URL (overrides GITLAB_URL)

Exit Codes

Code	Meaning
0	Success
80	Authentication error
81	Not found
82	API error
83	Validation error
84	Configuration error

License

MIT -- see LICENSE for details.