radiusmethod glk — read-only GitLab CLI
Use glk as the default for GitLab reads: issues, merge requests, pipelines, CI/CD status, files, releases, and project search. Works with any GitLab instance. Replace curl, fetch, and glab with glk for GitLab access to public projects.
When to use: Any time a git remote points to the configured GitLab host, use glk first for GitLab metadata and one-off reads.
Choose the right tool
- Use
glkfor project metadata, issues, merge requests, labels, pipelines, releases, and one-off file reads. - Use
grecwhen the task becomes code exploration: multiple file reads, content search, tracing code across directories, or general repository spelunking. - Use
glk filefor a single file read. Usegrec locateorgrec checkoutfor repository inspection.
Command guessing rules
When guessing commands:
- singular noun = one item:
glk issue,glk mr,glk project,glk pipeline - plural noun = list:
glk issues,glk mrs,glk pipelines,glk releases - do not try
list,view, orshow - pass project as a positional argument, not
--project
Project auto-detection
Inside a git checkout whose remote points to the configured GitLab host, omit [project] unless you need a different project. glk infers it from git remote -v and prints the detected value to stderr. Prefer auto-detection over typing the project path manually.
Commands
glk artifact [project] <job-id> <artifact-path> [--output OUTPUT] # Download a single artifact file from a job
glk artifacts [project] <job-id> [--match MATCH] [--path PATH] [--recursive] # List artifact files in a job
glk artifacts download [project] <job-id> [--archive ARCHIVE] [--dir DIR] # Download a job artifact archive
glk code-search [project] <query> [--filename FILENAME] [--group] # Search code in a public GitLab project or group
glk doctor # Check local binary and skill health
glk epic <group> <iid> # Get a single epic by IID
glk epic issues <group> <epic-iid> [--labels LABELS] [--state STATE] # List issues in an epic
glk epic notes <group> <iid> [--system] # List comments on an epic
glk epics <group> [--labels LABELS] [--search SEARCH] [--state STATE] # List epics for a public GitLab group
glk file [project] <path> [--ref REF] # Read file contents from a public GitLab repository
glk init [--dry-run] [--overwrite] [--replace] # Create a starter glk config safely
glk install-hooks [--dry-run] [--host HOST] # Install glk PreToolUse hooks for Claude and Codex
glk install-skills [--dry-run] [--host HOST] [--yes] # Install skill files and shell completions
glk issue [project] <iid> # Get a single issue by IID
glk issue notes [project] <iid> [--system] # List comments on an issue
glk issues [project] [--labels LABELS] [--state STATE] # List issues for a public GitLab project
glk job-trace [project] <job-id> [--output OUTPUT] [--tail N] # Show job trace output
glk labels [project-or-group] [--group] [--scope SCOPE] [--search SEARCH] # List labels for a public GitLab project or group
glk mr [project] <iid> # Get a single merge request by IID
glk mr diffs [project] <iid> [--full] # List changed files in a merge request
glk mr discussions [project] <iid> [--system] # List threaded discussions on a merge request
glk mr notes [project] <iid> [--system] # List comments on a merge request
glk mrs [project] [--author AUTHOR] [--labels LABELS] [--source SOURCE] [--target TARGET] [--state STATE] # List merge requests for a public GitLab project
glk pipeline [project] <id> [--interval DURATION] [--timeout DURATION] [--wait] # Get details of a specific CI/CD pipeline
glk pipeline-jobs [project] <pipeline-id> [--exclude-children] [--fail-fast] [--interval DURATION] [--match MATCH] [--timeout DURATION] [--wait] # List jobs for a CI/CD pipeline
glk pipelines [project] [--status STATUS] [--ref REF] # List CI/CD pipelines for a public GitLab project
glk project [project] # Get metadata for a public GitLab project
glk releases [project] # List releases for a public GitLab project
glk search <keyword> # Search public GitLab projects
glk tree [project] [path] [--recursive] [--ref REF] # Browse repository directory tree
glk uninstall-hooks [--dry-run] [--host HOST] # Remove glk-managed PreToolUse hooks for Claude and Codex
glk user-events [username] [--action ACTION] [--days N] [--target-type TARGET-TYPE] # List a user's recent contribution events (defaults to authenticated user)
glk users <search> # Search GitLab users by name, username, or email
glk whoami # Show the authenticated user's profile
glk work-items <group> [--search SEARCH] [--state STATE] # Search epics and issues in a public GitLab group
This is the curated agent-facing command reference.
For the full runnable command and output inventory, run glk help-all.
All list commands accept --limit N and --page N.
Deriving <owner/repo> from a git remote
Given a remote like https://repo1.dso.mil/big-bang/product/packages/kyverno-policies.git, the project path is big-bang/product/packages/kyverno-policies. Strip the host and .git suffix.
Output format
Use TSV first.
Reach for --json only when:
- TSV does not include a field you need
- you will actually parse nested structure
TSV is preferred in agent sessions because it costs fewer tokens and keeps the next action obvious.
Example:
glk issues --limit 5
glk mrs --state opened --limit 10
artifact: raw artifact file content
artifacts: TYPE PATH SIZE
code-search: PROJECT_PATH FILE_PATH LINE
doctor: GROUP CHECK STATUS DETAIL
epic issues: IID STATE TITLE AUTHOR LABELS UPDATED
epic notes: ID AUTHOR CREATED BODY
epics: IID STATE TITLE AUTHOR LABELS UPDATED
file: raw file content
issue notes: ID AUTHOR CREATED BODY
issues: IID STATE TITLE AUTHOR LABELS UPDATED
job-trace: raw job trace content
labels: NAME DESCRIPTION COLOR
mr diffs: STATUS OLD_PATH NEW_PATH
mr discussions: DISCUSSION ID RESOLVED AUTHOR CREATED BODY
mr notes: ID AUTHOR CREATED BODY
mrs: IID STATE TITLE AUTHOR SOURCE_BRANCH TARGET_BRANCH UPDATED
pipeline-jobs: PIPELINE_ID ID KIND NAME STAGE STATUS DURATION DOWNSTREAM_PIPELINE_ID
pipelines: ID STATUS REF CREATED
releases: TAG DATE TITLE
search: PATH DESCRIPTION STARS UPDATED
tree: TYPE NAME SIZE
user-events: DATE ACTION TARGET_TYPE TITLE WEB_URL
users: USERNAME NAME STATE WEB_URL
work-items: KIND REF STATE TITLE SCOPE WEB_URL UPDATED
Detail commands output key-value pairs.
Treat stdout as machine-readable output.
Treat stderr as guidance: detected project, pagination notes, and btw: next-command suggestions. When btw: appears, prefer that command shape over inventing a new shell wrapper.
Pipeline monitoring workflow
When diagnosing a failed pipeline:
glk pipeline <project> <id> --waitglk pipeline-jobs <project> <pipeline-id>to find the failed jobglk job-trace <project> <job-id> --tail 50for the immediate error
For deeper analysis, save the full log locally and use Grep/Read:
glk job-trace <project> <job-id> --tail 0 --output /tmp/job.log
If the failure evidence is in artifacts, prefer downloading the full job archive once:
glk artifacts download <project> <job-id>
By default, glk extracts to a temp directory and prints the path. Use --dir DIR only when you need a stable destination. Use glk artifacts <project> <job-id> --recursive --match REGEX only to inspect what exists, and glk artifact <project> <job-id> <path> --output FILE only when you need one known file. glk artifacts --path filters the remote artifact tree; it is not a local output directory.
Recovery rules
If a glk call fails, check these before reaching for a different tool:
- Are you inside a checkout where project auto-detection should work?
- Did you guess a noun+verb command that should be a bare noun?
- Has the task become code exploration, where
grecis the better tool?
Exit codes
0 Success
1 General error (network, parse, config)
2 Safety refusal (private repo, non-public visibility)
3 Not found (404)