Quickstart

GitLab Activity CLI - Agent Quickstart

Purpose

Retrieve GitLab user activity for agent consumption with structured output and minimal dependencies.

When to Use

• When agents need to check recent GitLab activity
• When analyzing user contribution patterns
• When generating activity reports
• When monitoring project engagement

Basic Usage

Get current user's activity (last 7 days)

gitlab-activity-cli me --instance https://gitlab.com --token ~/.gitlab/token

Get activity from specific GitLab instance

gitlab-activity-cli me --instance https://git.example.com --token ~/.gitlab/token

Get activity for specific time range

gitlab-activity-cli me --days 2 --instance https://gitlab.com --token ~/.gitlab/token
gitlab-activity-cli me --since 2026-05-21 --until 2026-05-22 --instance https://gitlab.com --token ~/.gitlab/token

Filter by project

gitlab-activity-cli me --project myproject --instance https://gitlab.com --token ~/.gitlab/token

Get activity for specific user

gitlab-activity-cli user username --days 3 --instance https://gitlab.com --token ~/.gitlab/token

Machine-Readable Output

JSON format for parsing

gitlab-activity-cli me --json --instance https://gitlab.com --token ~/.gitlab/token

Returns structured JSON with version field for schema stability:

{
  "version": "1.0",
  "user": "username",
  "instance": "https://gitlab.com",
  "period": {"days": 7},
  "total_events": 8,
  "projects": [...]
}

Token Configuration

Both --instance and --token flags are required for all operations.

Exit Codes for Automation

• 0 - Success
• 85 - Invalid arguments
• 92 - Resource not found (user not found)
• 100 - API error (connection failed, auth failed)
• 110 - Internal error

Common Agent Patterns

Check if user has activity today

gitlab-activity-cli me --days 1 --json --instance https://gitlab.com --token ~/.gitlab/token | jq '.total_events > 0'

Get commit messages from specific project

gitlab-activity-cli me --project myproject --json --instance https://gitlab.com --token ~/.gitlab/token | \
  jq -r '.projects[].activity[] | select(.push_data.commit_title != "") | .push_data.commit_title'

Monitor daily activity count

gitlab-activity-cli me --days 1 --json --instance https://gitlab.com --token ~/.gitlab/token | jq '.total_events'

Notes

• Default time range: last 7 days
• Maximum events per request: 100
• Output format: structured text (default) or JSON
• Non-interactive: all operations via flags