glab

Original source / Raw SKILL.md

---
name: glab
description: GitLab CLI for managing issues, merge requests, CI/CD pipelines, and repositories. Use when: (1) Creating, reviewing, or merging MRs, (2) Managing GitLab issues, (3) Monitoring or triggering CI/CD pipelines, (4) Working with self-hosted GitLab instances, (5) Automating GitLab workflows from the command line. Requires GITLAB_TOKEN (recommend minimal scopes). The `glab api` command enables arbitrary API calls - use read-only tokens when possible.
homepage: https://github.com/bezko/openclaw-skills/tree/main/skills/glab
metadata:
  openclaw:
    requires:
      bins: [glab, jq]
      envs:
        - name: GITLAB_TOKEN
          description: GitLab personal access token. Recommend minimal scopes (read_api for read-only).
          secret: true
          required: true
        - name: GITLAB_HOST
          description: GitLab instance hostname (e.g., gitlab.example.org). Defaults to gitlab.com.
          required: false
        - name: TIMEOUT
          description: Pipeline/MR wait timeout in seconds. Defaults vary by script.
          required: false
        - name: INTERVAL
          description: Polling interval in seconds for watch scripts. Default 5-10s.
          required: false
    install:
      - id: brew
        kind: brew
        package: glab
        label: Install glab via Homebrew
      - id: apt
        kind: apt
        package: glab
        label: Install glab via apt
      - id: jq-brew
        kind: brew
        package: jq
        label: Install jq via Homebrew
      - id: jq-apt
        kind: apt
        package: jq
        label: Install jq via apt
---

# GitLab CLI (glab)

Official CLI for GitLab. Manage issues, merge requests, pipelines, and more from the terminal.

> **Source:** Inspired by [NikiforovAll/glab-skill](https://github.com/NikiforovAll/claude-code-rules/tree/main/plugins/handbook-glab/skills/glab-skill) on Smithery.

## ⚠️ Security Notice

**The `glab api` command provides unrestricted GitLab API access with your token.**

- A compromised or overly-permissive token can delete projects, modify settings, expose secrets
- **Recommendation:** Use tokens with minimal scopes:
  - `read_api` - Read-only operations
  - `api` - Full access (only when write operations needed)
- For automation, consider project-level tokens with limited scope
- Never use tokens with `sudo` scope unless required

## Prerequisites

**Required binaries:**
- `glab` - GitLab CLI
- `jq` - JSON processor (for scripts and API parsing)

**Required credentials:**
- `GITLAB_TOKEN` - GitLab personal access token

**Optional configuration:**
- `GITLAB_HOST` - Self-hosted GitLab instance (default: gitlab.com)

```bash
# Verify installation
glab --version
jq --version

# Authenticate (interactive)
glab auth login

# Or via environment
export GITLAB_TOKEN="glpat-xxxxxxxxxxxxxxxxxxxx"
export GITLAB_HOST="gitlab.example.org"  # for self-hosted

# Verify auth
glab auth status
```

## Quick Reference

**Merge Requests:**
```bash
glab mr create --title "Fix" --description "Closes #123"
glab mr list --reviewer=@me          # MRs awaiting your review
glab mr checkout 123                  # Test MR locally
glab mr approve 123 && glab mr merge 123
```

**Issues:**
```bash
glab issue create --title "Bug" --label=bug
glab issue list --assignee=@me
glab issue close 456
```

**CI/CD:**
```bash
glab ci status                        # Current pipeline status
glab pipeline ci view                 # Watch pipeline live
glab ci lint                          # Validate .gitlab-ci.yml
glab ci retry                         # Retry failed pipeline
```

**Working Outside Repo:**
```bash
glab mr list -R owner/repo            # Specify repository
```

**Advanced API Access:**

See **references/api-advanced.md** for `glab api` usage. This command enables arbitrary GitLab API calls and should be used with appropriately-scoped tokens.

## Core Workflows

### Create and Merge MR

```bash
# 1. Push branch
git push -u origin feature-branch

# 2. Create MR
glab mr create --title "Add feature" --description "Implements X" --reviewer=alice,bob --label="enhancement"

# 3. After approval, merge
glab mr approve 123
glab mr merge 123 --remove-source-branch
```

### Review MR

```bash
# List MRs for review
glab mr list --reviewer=@me

# Checkout and test
glab mr checkout 123

# Approve or comment
glab mr approve 123
glab mr note 123 -m "Looks good, just one suggestion..."
```

### Monitor Pipeline

```bash
# Watch current branch pipeline
glab pipeline ci view

# Check specific pipeline
glab ci view 456

# View failed job logs
glab ci trace

# Retry
glab ci retry
```

## Self-Hosted GitLab

```bash
# Set default host
export GITLAB_HOST=gitlab.example.org

# Or per-command
glab mr list -R gitlab.example.org/owner/repo
```

## Scripts

| Script | Description |
|--------|-------------|
| `glab-mr-await.sh` | Wait for MR approval and successful pipeline |
| `glab-pipeline-watch.sh` | Monitor pipeline with exit codes for CI |

```bash
# Wait for MR to be approved and merged
./scripts/glab-mr-await.sh 123 --timeout 600

# Watch pipeline, exit 0 on success, 1 on failure
./scripts/glab-pipeline-watch.sh --timeout 300
```

**Script environment variables:**
- `TIMEOUT` - Max wait time in seconds (default varies by script)
- `INTERVAL` - Polling interval in seconds (default 5-10s)

## Troubleshooting

| Error | Fix |
|-------|-----|
| `command not found: glab` | Install glab |
| `command not found: jq` | Install jq |
| `401 Unauthorized` | Set `GITLAB_TOKEN` or run `glab auth login` |
| `404 Project Not Found` | Verify repo name and permissions |
| `not a git repository` | Use `-R owner/repo` flag |
| `source branch already has MR` | `glab mr list` to find existing |

For detailed troubleshooting, see **references/troubleshooting.md**.

## Progressive Disclosure

- **references/api-advanced.md** - `glab api` usage with security considerations
- **references/commands-detailed.md** - Full command reference with all flags
- **references/troubleshooting.md** - Detailed error scenarios and solutions

Load these when you need specific flag details or are debugging issues.

## Best Practices

1. Always verify auth: `glab auth status`
2. Use minimal-scope tokens for read operations
3. Link MRs to issues: "Closes #123" in description
4. Lint CI config before pushing: `glab ci lint`
5. Use `--output=json` for scripting
6. Most commands have `--web` to open in browser


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### scripts/glab-mr-await.sh

```bash
#!/usr/bin/env bash
#
# Wait for MR to be approved and pipeline to succeed.
# Exits 0 when merged, 1 on failure/timeout.
#
# Usage:
#   glab-mr-await.sh <mr-number> [--timeout SECONDS] [--require-approval]
#
# Examples:
#   glab-mr-await.sh 123                    # Wait for merge
#   glab-mr-await.sh 123 --timeout 600      # 10 min timeout
#   glab-mr-await.sh 123 --require-approval # Require at least one approval
#

set -euo pipefail

MR_NUMBER="${1:-}"
TIMEOUT="${TIMEOUT:-3600}"  # Default 1 hour
REQUIRE_APPROVAL=false
INTERVAL=10

usage() {
    echo "Usage: $0 <mr-number> [--timeout SECONDS] [--require-approval]"
    exit 1
}

# Parse args
shift || true
while [[ $# -gt 0 ]]; do
    case $1 in
        --timeout|-t)
            TIMEOUT="$2"
            shift 2
            ;;
        --require-approval|-a)
            REQUIRE_APPROVAL=true
            shift
            ;;
        *)
            usage
            ;;
    esac
done

[[ -z "$MR_NUMBER" ]] && usage

# Check glab
command -v glab >/dev/null || { echo "Error: glab not installed"; exit 1; }

echo "⏳ Waiting for MR !${MR_NUMBER} (timeout: ${TIMEOUT}s)"

START_TIME=$(date +%s)

check_mr() {
    local mr_json
    mr_json=$(glab mr view "$MR_NUMBER" --output=json 2>/dev/null) || return 1
    
    local state merged approvals
    state=$(echo "$mr_json" | jq -r '.state')
    merged=$(echo "$mr_json" | jq -r '.merged_at // empty')
    approvals=$(echo "$mr_json" | jq -r '.user.can_merge')
    
    # Check if merged
    if [[ "$state" == "merged" ]] || [[ -n "$merged" ]]; then
        echo "✅ MR !${MR_NUMBER} has been merged!"
        return 0
    fi
    
    # Check if closed
    if [[ "$state" == "closed" ]]; then
        echo "❌ MR !${MR_NUMBER} was closed"
        return 1
    fi
    
    # Check approval if required
    if [[ "$REQUIRE_APPROVAL" == "true" ]]; then
        local approval_count
        approval_count=$(glab api "projects/:id/merge_requests/${MR_NUMBER}/approvals" 2>/dev/null | jq -r '.approved_by | length')
        if [[ "$approval_count" -eq 0 ]]; then
            echo "⏳ Waiting for approval... (state: $state)"
            return 2  # Continue waiting
        fi
    fi
    
    # Check pipeline status
    local pipeline_status
    pipeline_status=$(glab ci status --output=json 2>/dev/null | jq -r '.status // "unknown"')
    
    case "$pipeline_status" in
        success)
            echo "✅ Pipeline passed. Waiting for merge..."
            ;;
        failed|canceled)
            echo "❌ Pipeline $pipeline_status"
            return 1
            ;;
        running|pending)
            echo "⏳ Pipeline $pipeline_status..."
            ;;
    esac
    
    return 2  # Continue waiting
}

while true; do
    ELAPSED=$(($(date +%s) - START_TIME))
    
    if [[ $ELAPSED -ge $TIMEOUT ]]; then
        echo "⏰ Timeout after ${TIMEOUT}s"
        exit 1
    fi
    
    if check_mr; then
        exit 0
    elif [[ $? -eq 1 ]]; then
        exit 1
    fi
    
    sleep "$INTERVAL"
done

```

### scripts/glab-pipeline-watch.sh

```bash
#!/usr/bin/env bash
#
# Watch pipeline and exit with appropriate code.
# Exits 0 on success, 1 on failure, 2 on timeout.
#
# Usage:
#   glab-pipeline-watch.sh [--timeout SECONDS] [--interval SECONDS]
#
# Examples:
#   glab-pipeline-watch.sh                  # Watch current branch pipeline
#   glab-pipeline-watch.sh --timeout 300    # 5 min timeout
#

set -euo pipefail

TIMEOUT="${TIMEOUT:-1800}"  # Default 30 min
INTERVAL="${INTERVAL:-5}"

# Parse args
while [[ $# -gt 0 ]]; do
    case $1 in
        --timeout|-t)
            TIMEOUT="$2"
            shift 2
            ;;
        --interval|-i)
            INTERVAL="$2"
            shift 2
            ;;
        *)
            shift
            ;;
    esac
done

command -v glab >/dev/null || { echo "Error: glab not installed"; exit 1; }
command -v jq >/dev/null || { echo "Error: jq not installed"; exit 1; }

START_TIME=$(date +%s)
PIPELINE_ID=""

echo "⏳ Watching pipeline (timeout: ${TIMEOUT}s)"

check_pipeline() {
    local status_json
    status_json=$(glab ci status --output=json 2>/dev/null) || return 3
    
    local status pipeline_id
    status=$(echo "$status_json" | jq -r '.status // "unknown"')
    pipeline_id=$(echo "$status_json" | jq -r '.id // empty')
    
    [[ -n "$pipeline_id" ]] && PIPELINE_ID="$pipeline_id"
    
    local elapsed=$(($(date +%s) - START_TIME))
    local spinner=("⠋" "⠙" "⠹" "⠸" "⠼" "⠴" "⠦" "⠧" "⠇" "⠏")
    local spin_idx=$((elapsed % ${#spinner[@]}))
    local spin="${spinner[$spin_idx]}"
    
    case "$status" in
        success)
            echo -e "\r✅ Pipeline #${PIPELINE_ID} succeeded! (${elapsed}s)  "
            return 0
            ;;
        failed)
            echo -e "\r❌ Pipeline #${PIPELINE_ID} failed (${elapsed}s)  "
            echo "Run 'glab ci trace' to see logs"
            return 1
            ;;
        canceled)
            echo -e "\r🚫 Pipeline #${PIPELINE_ID} was canceled  "
            return 1
            ;;
        running|pending|created)
            printf "\r%s Pipeline #%s %s... (%ds)  " "$spin" "${PIPELINE_ID:-?}" "$status" "$elapsed"
            return 3
            ;;
        *)
            printf "\r%s Pipeline status: %s (%ds)  " "$spin" "$status" "$elapsed"
            return 3
            ;;
    esac
}

while true; do
    ELAPSED=$(($(date +%s) - START_TIME))
    
    if [[ $ELAPSED -ge $TIMEOUT ]]; then
        echo -e "\r⏰ Timeout after ${TIMEOUT}s  "
        exit 2
    fi
    
    if check_pipeline; then
        exit 0
    else
        local ret=$?
        [[ $ret -eq 1 ]] && exit 1
        [[ $ret -eq 3 ]] && sleep "$INTERVAL" && continue
        exit $ret
    fi
done

```



---

## Skill Companion Files

> Additional files collected from the skill directory layout.

### _meta.json

```json
{
  "owner": "bezkom",
  "slug": "glab",
  "displayName": "glab",
  "latest": {
    "version": "1.0.4",
    "publishedAt": 1772309223990,
    "commit": "https://github.com/openclaw/skills/commit/f68feb80a107a9cd4f0268211a0e42741ee761d0"
  },
  "history": [
    {
      "version": "1.0.2",
      "publishedAt": 1772305072850,
      "commit": "https://github.com/openclaw/skills/commit/2ef9047d05036972ce13d3de71c660263bd3388a"
    }
  ]
}

```

### references/api-advanced.md

```markdown
# glab api - Advanced API Access

> ⚠️ **Security Warning**: This command provides unrestricted GitLab API access with your authenticated token. A compromised or overly-permissive token can delete projects, modify settings, expose secrets, and perform other destructive operations.

## Token Scope Recommendations

| Scope | Access Level | Use Case |
|-------|--------------|----------|
| `read_api` | Read-only | Viewing projects, issues, MRs |
| `api` | Full read/write | Creating/updating/deleting resources |
| `sudo` | Admin actions | Only for admin tasks (avoid if possible) |

**Best practice:** Use `read_api` scope tokens for read-only operations. Only use `api` scope when write operations are required.

## Basic Usage

```bash
# GET request
glab api projects/:id/merge_requests

# With pagination (use query params, NOT flags)
glab api "projects/:id/merge_requests?per_page=100&state=opened"

# Auto-fetch all pages
glab api --paginate "projects/:id/jobs?per_page=100"
```

## POST/PUT/DELETE Requests

```bash
# POST with data
glab api --method POST projects/:id/issues \
  --field title="Bug" \
  --field description="Details"

# PUT (update)
glab api --method PUT projects/:id/issues/123 \
  --field state_event="close"

# DELETE
glab api --method DELETE projects/:id/issues/123
```

## Common Patterns

### List Unresolved MR Comments

```bash
glab api "projects/:id/merge_requests/{mr}/discussions?per_page=100" | \
  jq '[.[] | select(.notes[0].resolvable == true and .notes[0].resolved == false) | \
  {id: .notes[0].id, body: .notes[0].body[0:100], path: .notes[0].position.new_path}]'
```

### Reply to Discussion Threads

`glab mr note` creates standalone comments. To reply within a thread:

```bash
# 1. Find the discussion_id containing the note
glab api "projects/:id/merge_requests/{mr}/discussions" | \
  jq '.[] | select(.notes[].id == {note_id}) | .id'

# 2. Post reply to the discussion thread
glab api --method POST \
  "projects/:id/merge_requests/{mr}/discussions/{discussion_id}/notes" \
  --field body="Your reply"
```

### Get Pipeline Jobs

```bash
glab api --paginate "projects/:id/pipelines/{pipeline_id}/jobs?per_page=100"
```

### Trigger Pipeline

```bash
glab api --method POST projects/:id/pipeline \
  --field ref="main"
```

## Safety Patterns

1. **Dry-run first**: Use GET to verify before POST/PUT/DELETE
2. **Limit scope**: Use project-level tokens instead of personal tokens when possible
3. **Audit trail**: GitLab logs API calls - review activity periodically
4. **Rate limiting**: GitLab has API rate limits; use `--paginate` for large datasets

## Error Handling

```bash
# Check response status
glab api projects/:id/merge_requests 2>&1 | head -1

# Handle errors in scripts
if ! glab api projects/:id >/dev/null 2>&1; then
  echo "API call failed"
  exit 1
fi
```

## API Documentation

- [GitLab REST API](https://docs.gitlab.com/ee/api/)
- [glab api docs](https://docs.gitlab.com/editor_extensions/gitlab_cli/)

```

### references/commands-detailed.md

```markdown
# glab Commands - Detailed Reference

This is a comprehensive reference for all glab commands. This file is loaded when detailed command information is needed.

## Merge Requests (MR)

### Listing Merge Requests
```bash
# List MRs assigned to you
glab mr list --assignee=@me

# List MRs where you're a reviewer
glab mr list --reviewer=@me

# List all open MRs
glab mr list

# Filter by state
glab mr list --state=merged
glab mr list --state=closed
glab mr list --state=all
```

### Creating Merge Requests
```bash
# Create MR from current branch (interactive)
glab mr create

# Create MR with title and description
glab mr create --title "Fix bug" --description "Fixes issue #123"

# Create MR for specific issue
glab mr create 123

# Create draft MR
glab mr create --draft

# Create MR and assign reviewers
glab mr create --reviewer=username1,username2

# Create MR with labels
glab mr create --label="bug,priority:high"

# Create MR with assignee
glab mr create --assignee=username

# Create MR to a specific target branch
glab mr create --target-branch=develop

# Create MR and remove source branch after merge
glab mr create --remove-source-branch
```

### Viewing and Interacting with MRs
```bash
# View MR details (opens in browser by default)
glab mr view 123

# View MR in terminal
glab mr view 123 --web=false

# View MR with comments
glab mr view 123 --comments

# Checkout MR branch locally
glab mr checkout 243

# Approve MR
glab mr approve 123

# Unapprove MR
glab mr unapprove 123

# Merge MR
glab mr merge 123

# Merge and delete source branch
glab mr merge 123 --remove-source-branch

# Close MR without merging
glab mr close 123

# Reopen closed MR
glab mr reopen 123

# Add note/comment to MR
glab mr note 123 -m "Looks good to me"

# Update MR title
glab mr update 123 --title "New title"

# Update MR description
glab mr update 123 --description "New description"

# Mark MR as draft
glab mr update 123 --draft

# Mark MR as ready (remove draft status)
glab mr update 123 --ready

# Subscribe to MR notifications
glab mr subscribe 123

# Unsubscribe from MR notifications
glab mr unsubscribe 123
```

## Issues

### Listing Issues
```bash
# List all issues
glab issue list

# List issues assigned to you
glab issue list --assignee=@me

# List issues with specific label
glab issue list --label=bug

# List issues with multiple labels
glab issue list --label="bug,priority:high"

# List closed issues
glab issue list --state=closed

# List all issues (open and closed)
glab issue list --state=all

# Search issues
glab issue list --search="login error"

# List issues assigned to specific user
glab issue list --assignee=username
```

### Creating and Managing Issues
```bash
# Create issue interactively
glab issue create

# Create issue with title and description
glab issue create --title "Bug in login" --description "Users cannot log in"

# Create issue with labels
glab issue create --title "Feature request" --label="enhancement,feature"

# Create issue with assignee
glab issue create --title "Fix bug" --assignee=username

# Create confidential issue
glab issue create --title "Security issue" --confidential

# View issue details
glab issue view 456

# View issue in browser
glab issue view 456 --web

# Close issue
glab issue close 456

# Close with a comment
glab issue close 456 -m "Fixed in MR !123"

# Reopen issue
glab issue reopen 456

# Update issue title
glab issue update 456 --title "New title"

# Update issue description
glab issue update 456 --description "New description"

# Add labels to issue
glab issue update 456 --label="bug,confirmed"

# Assign issue
glab issue update 456 --assignee=username

# Subscribe to issue
glab issue subscribe 456

# Unsubscribe from issue
glab issue unsubscribe 456
```

## CI/CD Pipelines

### Viewing Pipelines
```bash
# Watch pipeline in progress (interactive)
glab pipeline ci view

# List recent pipelines
glab ci list

# List pipelines with specific status
glab ci list --status=failed
glab ci list --status=success
glab ci list --status=running

# View specific pipeline status
glab ci status

# View pipeline for specific branch
glab ci status --branch=main

# Get pipeline trace/logs
glab ci trace

# Get trace for specific job
glab ci trace <job-id>

# View pipeline details
glab ci view <pipeline-id>

# Delete a pipeline
glab ci delete <pipeline-id>
```

### Triggering and Managing Pipelines
```bash
# Run/trigger pipeline
glab ci run

# Run pipeline for specific branch
glab ci run --branch=develop

# Run pipeline with variables
glab ci run --variables-file /tmp/variables.json

# Run pipeline with inline variables
glab ci run -V KEY1=value1 -V KEY2=value2

# Retry failed pipeline
glab ci retry

# Retry specific pipeline
glab ci retry <pipeline-id>

# Cancel running pipeline
glab ci cancel

# Cancel specific pipeline
glab ci cancel <pipeline-id>
```

### CI Configuration
```bash
# Lint .gitlab-ci.yml file in current directory
glab ci lint

# Lint specific file
glab ci lint --path=.gitlab-ci.yml

# View CI configuration
glab ci config

# Get CI job artifacts
glab ci artifact <job-id>

# Download artifacts to specific path
glab ci artifact <job-id> -p path/to/download
```

## Repository Operations

### Cloning Repositories
```bash
# Clone repository
glab repo clone namespace/project

# Clone to specific directory
glab repo clone namespace/project target-dir

# Clone from self-hosted GitLab
GITLAB_HOST=gitlab.example.org glab repo clone groupname/project

# Clone repository by group (interactive)
glab repo clone -g groupname

# Clone with specific protocol
glab repo clone namespace/project --protocol=ssh
glab repo clone namespace/project --protocol=https
```

### Repository Information and Management
```bash
# View repository details
glab repo view

# View specific repository
glab repo view owner/repo

# View in browser
glab repo view --web

# Fork repository
glab repo fork

# Fork to specific namespace
glab repo fork --clone --namespace=mygroup

# Archive repository
glab repo archive owner/project

# Unarchive repository
glab repo unarchive owner/project

# Delete repository
glab repo delete owner/project

# Create repository
glab repo create project-name

# Create private repository
glab repo create project-name --private

# Create repository with description
glab repo create project-name --description "My project"

# Mirror repository
glab repo mirror source-repo target-repo
```

## API Access

### Making API Calls
```bash
# GET request
glab api projects/:id/merge_requests

# GET with specific project ID
glab api projects/12345/merge_requests

# POST request with data
glab api --method POST projects/:id/issues --field title="Bug report"

# POST with multiple fields
glab api --method POST projects/:id/issues \
  --field title="Bug" \
  --field description="Description here" \
  --field labels="bug,priority:high"

# PUT request
glab api --method PUT projects/:id/merge_requests/1 --field title="New Title"

# DELETE request
glab api --method DELETE projects/:id/issues/123

# Paginated API request (auto-fetches all pages)
glab api --paginate projects/:id/issues

# Pagination with query parameters (specify per_page in URL)
glab api "projects/:id/issues?per_page=100"

# Combine pagination flag with query parameters
glab api --paginate "projects/:id/merge_requests?per_page=50&state=opened"

# Manual pagination (specific page)
glab api "projects/:id/issues?page=2&per_page=100"

# Include response headers
glab api --include projects/:id

# Silent mode (no progress)
glab api --silent projects/:id/merge_requests
```

## Labels

```bash
# List all labels
glab label list

# Create label
glab label create "bug" --color="#FF0000"

# Create label with description
glab label create "feature" --color="#00FF00" --description "New features"

# Delete label
glab label delete "old-label"
```

## Releases

```bash
# List releases
glab release list

# Create release
glab release create v1.0.0

# Create release with notes
glab release create v1.0.0 --notes "Release notes here"

# Create release from file
glab release create v1.0.0 --notes-file CHANGELOG.md

# Create release with assets
glab release create v1.0.0 --asset-links='[{"name":"Asset","url":"https://..."}]'

# View specific release
glab release view v1.0.0

# Download release assets
glab release download v1.0.0

# Delete release
glab release delete v1.0.0
```

## Snippets

```bash
# List snippets
glab snippet list

# List all snippets (including private)
glab snippet list --all

# Create snippet
glab snippet create --title "Config" --filename config.yml

# Create snippet from file
glab snippet create --title "Script" myfile.sh

# Create private snippet
glab snippet create --title "Secret" --private secret.txt

# View snippet
glab snippet view <snippet-id>

# Delete snippet
glab snippet delete <snippet-id>
```

## User Operations

```bash
# View current user information
glab user view

# View specific user
glab user view username

# List user's events
glab user events

# List specific user's events
glab user events username
```

## Variables (CI/CD)

```bash
# List variables
glab variable list

# Get specific variable
glab variable get VAR_NAME

# Set/create variable
glab variable set VAR_NAME value

# Set protected variable
glab variable set VAR_NAME value --protected

# Set masked variable
glab variable set VAR_NAME value --masked

# Update variable
glab variable update VAR_NAME new-value

# Delete variable
glab variable delete VAR_NAME

# Export variables
glab variable export > variables.json

# Import variables
glab variable import < variables.json
```

## Additional Commands

### Aliases
```bash
# Create alias
glab alias set co "mr checkout"

# List aliases
glab alias list

# Delete alias
glab alias delete co
```

### SSH Keys
```bash
# List SSH keys
glab ssh-key list

# Add SSH key
glab ssh-key add ~/.ssh/id_rsa.pub

# Add SSH key with title
glab ssh-key add ~/.ssh/id_rsa.pub --title "Work laptop"

# Delete SSH key
glab ssh-key delete <key-id>
```

### Deploy Keys
```bash
# List deploy keys
glab deploy-key list

# Add deploy key
glab deploy-key add --title "CI/CD" --key "ssh-rsa ..."

# Delete deploy key
glab deploy-key delete <key-id>
```

### Schedules (Pipeline Schedules)
```bash
# List pipeline schedules
glab schedule list

# Create schedule
glab schedule create --cron "0 2 * * *" --ref main --description "Nightly build"

# Run schedule immediately
glab schedule run <schedule-id>

# Delete schedule
glab schedule delete <schedule-id>
```

## Common Flags Across Commands

Most glab commands support these common flags:

- `--help`, `-h` - Show help for command
- `--repo`, `-R` - Specify repository (format: OWNER/REPO)
- `--web`, `-w` - Open in web browser
- `--output`, `-o` - Output format (json, text, etc.)
- `--verbose` - Enable verbose output
- `--page`, `-p` - Page number for paginated results
- `--per-page`, `-P` - Number of items per page

## Output Formats

Many commands support different output formats:

```bash
# JSON output (useful for scripting)
glab mr list --output=json

# Pipe to jq for processing
glab mr list --output=json | jq '.[] | .title'
```

## Configuration Commands

```bash
# View all configuration
glab config get

# Get specific config value
glab config get editor

# Set configuration value
glab config set editor vim

# Common config keys:
# - editor: preferred text editor
# - browser: web browser to use
# - glamour_style: style for terminal rendering
# - host: default GitLab host
```

## Completion

```bash
# Generate completion script for bash
glab completion --shell bash

# For zsh
glab completion --shell zsh

# For fish
glab completion --shell fish

# For PowerShell
glab completion --shell powershell

# Install completion (bash example)
glab completion --shell bash > /etc/bash_completion.d/glab
```

## Version and Updates

```bash
# Show glab version
glab version

# Check for updates
glab check-update

# View changelog
glab changelog
```

```

### references/troubleshooting.md

```markdown
# glab Troubleshooting Guide

Comprehensive troubleshooting guide for common glab CLI issues and errors.

## Installation Issues

### Command Not Found

**Error:**
```
command not found: glab
```
or
```
glab: command not found
```

**Causes:**
- glab is not installed
- glab is not in PATH

**Solutions:**
1. Verify installation:
   ```bash
   which glab
   ```

2. Install glab if missing (see main README for installation instructions)

3. If installed but not in PATH, add to PATH:
   ```bash
   # Find where glab is installed
   find / -name glab 2>/dev/null

   # Add to PATH in ~/.bashrc or ~/.zshrc
   export PATH="$PATH:/path/to/glab"
   ```

4. For Go installation, ensure `$GOPATH/bin` is in PATH:
   ```bash
   export PATH="$PATH:$(go env GOPATH)/bin"
   ```

### Version Conflicts

**Error:**
```
glab: incompatible version
```

**Solution:**
Update to the latest version:
```bash
# macOS
brew upgrade glab

# Linux (depends on package manager)
sudo apt update && sudo apt upgrade glab
```

## Authentication Issues

### 401 Unauthorized

**Error:**
```
failed to get current user: GET https://gitlab.com/api/v4/user: 401 {message: 401 Unauthorized}
```

**Causes:**
- Not authenticated
- Token expired
- Invalid token
- Wrong GitLab instance

**Solutions:**
1. Authenticate:
   ```bash
   glab auth login
   ```

2. Check authentication status:
   ```bash
   glab auth status
   ```

3. Re-authenticate with new token:
   ```bash
   glab auth login --hostname gitlab.com --token YOUR_TOKEN
   ```

4. Verify token has correct scopes (api, read_user, write_repository)

5. For self-hosted GitLab, ensure correct hostname:
   ```bash
   glab auth login --hostname gitlab.example.org
   ```

### Token Permissions

**Error:**
```
403 Forbidden
```
or
```
insufficient permissions
```

**Causes:**
- Token lacks required scopes
- User doesn't have project permissions

**Solutions:**
1. Create new token with required scopes:
   - api
   - read_api
   - read_user
   - write_repository
   - read_repository

2. Verify project access in GitLab web UI

3. Check if project is private and token has access

### Multiple Accounts

**Issue:** Working with multiple GitLab instances

**Solution:**
glab supports multiple authenticated accounts:

```bash
# Authenticate with gitlab.com
glab auth login --hostname gitlab.com

# Authenticate with self-hosted instance
glab auth login --hostname gitlab.example.org

# Check all authenticated accounts
glab auth status

# Use specific host for command
glab mr list -R gitlab.example.org/namespace/project
```

## Repository Context Issues

### Not a Git Repository

**Error:**
```
fatal: not a git repository (or any of the parent directories): .git
```

**Causes:**
- Running glab outside a Git repository
- Git repository not initialized

**Solutions:**
1. Navigate to a Git repository:
   ```bash
   cd /path/to/your/repo
   ```

2. Or specify repository explicitly:
   ```bash
   glab mr list -R owner/repo
   ```

3. Initialize Git repository if needed:
   ```bash
   git init
   git remote add origin [email protected]:owner/repo.git
   ```

### Wrong Repository Detected

**Issue:** glab operating on wrong repository

**Solution:**
1. Check current repository remote:
   ```bash
   git remote -v
   ```

2. Specify correct repository:
   ```bash
   glab mr list -R owner/correct-repo
   ```

3. Update Git remote if wrong:
   ```bash
   git remote set-url origin [email protected]:owner/correct-repo.git
   ```

### 404 Project Not Found

**Error:**
```
404 Project Not Found
```

**Causes:**
- Repository doesn't exist
- Wrong namespace/project name
- No access permissions
- Wrong GitLab instance

**Solutions:**
1. Verify repository name:
   ```bash
   # Check in GitLab web UI
   # Correct format: namespace/project
   ```

2. Check you have access to the project

3. Verify GitLab instance:
   ```bash
   glab auth status
   ```

4. For self-hosted, set correct host:
   ```bash
   GITLAB_HOST=gitlab.example.org glab repo view
   ```

## Merge Request Issues

### Source Branch Already Has MR

**Error:**
```
failed to create merge request: source branch already has a merge request
```

**Cause:**
- A merge request already exists for this branch

**Solutions:**
1. List existing MRs to find it:
   ```bash
   glab mr list
   glab mr list --source-branch=$(git branch --show-current)
   ```

2. View the existing MR:
   ```bash
   glab mr view <mr-number>
   ```

3. Update existing MR instead of creating new one:
   ```bash
   glab mr update <mr-number> --title "New title"
   ```

### Cannot Merge: Conflicts Exist

**Error:**
```
Cannot merge: merge conflicts exist
```

**Solutions:**
1. Checkout MR locally:
   ```bash
   glab mr checkout <mr-number>
   ```

2. Fetch latest target branch:
   ```bash
   git fetch origin main
   ```

3. Merge or rebase:
   ```bash
   git merge origin/main
   # or
   git rebase origin/main
   ```

4. Resolve conflicts and push:
   ```bash
   git add .
   git commit
   git push
   ```

### Pipeline Must Succeed

**Error:**
```
cannot merge: pipeline must succeed
```

**Cause:**
- Project requires successful pipeline before merge
- Pipeline is failing or pending

**Solutions:**
1. Check pipeline status:
   ```bash
   glab ci status
   ```

2. View pipeline details:
   ```bash
   glab pipeline ci view
   ```

3. Fix pipeline failures and retry:
   ```bash
   glab ci retry
   ```

4. If project settings allow, force merge (not recommended):
   ```bash
   # Only if you have maintainer permissions
   glab mr merge <mr-number> --when-pipeline-succeeds
   ```

### Cannot Push to Source Branch

**Error:**
```
You cannot push commits to this source branch
```

**Cause:**
- MR is from a fork
- No write access to source repository

**Solution:**
Ask MR author to make changes, or:
1. Checkout MR:
   ```bash
   glab mr checkout <mr-number>
   ```

2. Make changes on their fork (requires special permissions)

## Pipeline/CI Issues

### Pipeline Not Found

**Error:**
```
pipeline not found
```

**Causes:**
- No pipeline exists for current branch
- Pipeline hasn't started yet

**Solutions:**
1. Trigger a pipeline:
   ```bash
   glab ci run
   ```

2. Check if .gitlab-ci.yml exists:
   ```bash
   ls -la .gitlab-ci.yml
   ```

3. Verify CI/CD is enabled in project settings

### CI Lint Errors

**Error:**
```
.gitlab-ci.yml is invalid
```

**Solutions:**
1. Lint locally:
   ```bash
   glab ci lint
   ```

2. Common issues:
   - YAML syntax errors (tabs vs spaces)
   - Invalid job names
   - Missing required fields
   - Incorrect indentation

3. Use GitLab CI/CD config validation in web UI

4. Check GitLab CI/CD documentation for syntax

### Cannot Download Artifacts

**Error:**
```
failed to download artifacts
```

**Causes:**
- Artifacts expired
- Job didn't produce artifacts
- Permission issues

**Solutions:**
1. Check if job has artifacts:
   ```bash
   glab ci view <pipeline-id>
   ```

2. Verify artifacts haven't expired (check project settings)

3. Run job again if needed:
   ```bash
   glab ci retry
   ```

## Network and Connection Issues

### Connection Timeout

**Error:**
```
dial tcp: i/o timeout
```

**Causes:**
- Network connectivity issues
- Firewall blocking connection
- GitLab instance down

**Solutions:**
1. Check network connection:
   ```bash
   ping gitlab.com
   ```

2. Verify GitLab status:
   ```bash
   curl -I https://gitlab.com
   ```

3. Check firewall/proxy settings

4. For self-hosted, verify hostname:
   ```bash
   ping gitlab.example.org
   ```

### SSL Certificate Issues

**Error:**
```
x509: certificate signed by unknown authority
```

**Causes:**
- Self-signed certificate
- Corporate proxy
- Invalid SSL certificate

**Solutions:**
1. For development/testing only (NOT production):
   ```bash
   export GIT_SSL_NO_VERIFY=true
   ```

2. Add certificate to system trust store (preferred)

3. Configure Git to use specific CA bundle:
   ```bash
   git config --global http.sslCAInfo /path/to/cert.pem
   ```

## Environment Variable Issues

### GITLAB_HOST Not Recognized

**Issue:** Commands still using gitlab.com instead of self-hosted instance

**Solutions:**
1. Export variable in current shell:
   ```bash
   export GITLAB_HOST=gitlab.example.org
   ```

2. Add to shell profile (~/.bashrc, ~/.zshrc):
   ```bash
   echo 'export GITLAB_HOST=gitlab.example.org' >> ~/.bashrc
   source ~/.bashrc
   ```

3. Or use flag for each command:
   ```bash
   glab mr list -R gitlab.example.org/owner/repo
   ```

### GITLAB_TOKEN Not Working

**Issue:** Token set but authentication still failing

**Solutions:**
1. Verify token is exported:
   ```bash
   echo $GITLAB_TOKEN
   ```

2. Ensure no spaces in token:
   ```bash
   export GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx
   ```

3. Token should not be quoted in export:
   ```bash
   # Correct
   export GITLAB_TOKEN=glpat-xxx

   # Incorrect
   export GITLAB_TOKEN="glpat-xxx"
   ```

4. Verify token is valid in GitLab web UI

## Output and Display Issues

### Garbled or Missing Output

**Issue:** Terminal output is corrupted or incomplete

**Solutions:**
1. Disable glamour styling:
   ```bash
   export GLAMOUR_STYLE=notty
   ```

2. Use plain text output:
   ```bash
   glab mr list --output=text
   ```

3. Update terminal emulator

4. Try different pager:
   ```bash
   export PAGER=less
   ```

### JSON Parsing Errors

**Issue:** Cannot parse JSON output

**Solutions:**
1. Ensure command supports JSON:
   ```bash
   glab mr list --output=json
   ```

2. Pipe through jq for validation:
   ```bash
   glab mr list --output=json | jq '.'
   ```

3. Check for error messages mixed with JSON

## Performance Issues

### Commands Running Slowly

**Causes:**
- Large repository
- Many results being fetched
- Network latency

**Solutions:**
1. Limit results:
   ```bash
   glab mr list --per-page=10 --page=1
   ```

2. Use specific filters:
   ```bash
   glab mr list --assignee=@me --state=opened
   ```

3. Disable web browser opening:
   ```bash
   glab mr view 123 --web=false
   ```

## Configuration Issues

### Config File Corruption

**Error:**
```
failed to load config
```

**Solutions:**
1. Check config file:
   ```bash
   cat ~/.config/glab-cli/config.yml
   ```

2. Backup and recreate:
   ```bash
   mv ~/.config/glab-cli/config.yml ~/.config/glab-cli/config.yml.bak
   glab auth login
   ```

3. Manually edit config:
   ```bash
   vim ~/.config/glab-cli/config.yml
   ```

## General Troubleshooting Steps

When encountering any error:

1. **Check version:**
   ```bash
   glab version
   ```

2. **Update glab:**
   ```bash
   glab check-update
   ```

3. **Enable verbose output:**
   ```bash
   glab <command> --verbose
   ```

4. **Check authentication:**
   ```bash
   glab auth status
   ```

5. **Verify repository context:**
   ```bash
   git remote -v
   ```

6. **Use --help:**
   ```bash
   glab <command> --help
   ```

7. **Check GitLab API status:**
   Visit https://status.gitlab.com

8. **Review logs:**
   ```bash
   # Check recent commands
   history | grep glab
   ```

## Getting Additional Help

If issues persist:

1. Check glab documentation: https://docs.gitlab.com/editor_extensions/gitlab_cli/
2. Search glab issues: https://gitlab.com/gitlab-org/cli/-/issues
3. Create a new issue with:
   - glab version
   - Operating system
   - Full error message
   - Steps to reproduce
   - Output with --verbose flag

```