Enhance CLI agent-friendliness for AI/LLM usage

Please select the appropriate template for submitting your issue from the dropdown above.

Summary

As AI agents and LLMs increasingly use CLI tools directly, we should enhance glab to better support programmatic agent usage. While glab already has excellent MCP server support, agents often invoke CLI tools directly and need runtime discovery of capabilities and alternatives.

Background

Research shows emerging patterns for agent-friendly CLI design (see The Hidden Users: Designing CLI Tools for AI Agents):

Runtime capability discovery via flags like --agent-info
Structured JSON output everywhere
Clear alternatives to interactive commands
Machine-readable error responses
Consistent exit codes with documented meanings

What glab already does well:

✅ MCP server support (glab mcp serve)
✅ JSON output on most commands (--output json)
✅ NO_PROMPT=true for non-interactive mode
✅ MCP annotations for interactive commands

What's missing: Runtime discovery mechanism for agents to learn about these capabilities.

Proposals

Tier 1: Quick Wins (High Impact, Low Effort)

1. Add `--agent-info` Discovery Flag

Add a glab --agent-info flag that returns structured JSON with capabilities:

{
  "version": "1.84.0",
  "mcp_server_available": true,
  "json_output_supported": true,
  "environment_hints": {
    "NO_PROMPT": "Set to true to disable interactive prompts",
    "NO_COLOR": "Disable ANSI color codes",
    "GITLAB_TOKEN": "Provide authentication token"
  },
  "interactive_commands": [
    {"cmd": "ci view", "use_instead": "ci get <id> --output json"},
    {"cmd": "config edit", "use_instead": "config set <key> <value>"},
    {"cmd": "duo ask", "use_instead": "duo ask --prompt 'question'"}
  ],
  "json_output_commands": ["mr list", "issue list", "ci list", "ci get"],
  "docs_url": "https://docs.gitlab.com/cli/"
}

Benefits: Agents can discover capabilities at runtime without external documentation.

2. Improve Error Messages for Interactive Commands

When agents try interactive commands without TTY, provide helpful alternatives:

Error: 'glab ci view' requires an interactive terminal.

💡 For programmatic access, try:
  glab ci get 12345 --output json
  glab ci list --output json

Or use the MCP server: glab mcp serve

Implementation: Check f.IO().IsTerminal() in interactive commands and provide guidance.

3. Add Agent Usage Section to Help

Enhance glab --help to include:

  AGENT USAGE
  
    For AI agents and automation:
    - Use --output json for structured data
    - Set NO_PROMPT=true to disable interactive prompts
    - Run 'glab --agent-info' for capabilities and alternatives
    - Use 'glab mcp serve' for Model Context Protocol support

Tier 2: Medium-Term Improvements

4. Document and Standardize Exit Codes

Consistent exit codes across all commands:

0 = Success
1 = General error
2 = Usage error (bad flags)
3 = Authentication error
4 = Not found
130 = Interrupted

Document in help text: "Exit codes: 0=success, 1=error, 3=auth, 4=not found"

5. Audit JSON Output Support

Ensure all list, view, get commands support --output json consistently.

6. Add `glab doctor` Command

Diagnostic command for troubleshooting agent issues:

$ glab doctor
✓ Authentication: Configured (gitlab.com)
✓ JSON output: Supported
✓ MCP server: Available
✓ Network: Reachable
✓ Git repo: Detected (gitlab-org/cli)
! Warning: Running in CI environment (detected CI=true)

Tier 3: Future Enhancements

7. Structured Error Responses

When using --output json, return structured errors:

{
  "error": {
    "code": "authentication_failed",
    "message": "Invalid or expired token",
    "retryable": false,
    "category": "auth",
    "suggestion": "Run 'glab auth login' or set GITLAB_TOKEN"
  }
}

8. Machine-Readable Help

Add glab <command> --help --format json for programmatic help parsing.

Priority

Feature	Impact	Effort	Priority
`--agent-info` flag	High	Low	P1
Better error messages	High	Low	P1
Agent section in help	Medium	Low	P1
Consistent exit codes	Medium	Medium	P2
`glab doctor` command	Medium	Medium	P2
Structured errors	Medium	High	P3

Existing MCP implementation: internal/commands/mcp/serve/
MCP annotations: internal/mcpannotations/annotations.go
Environment variables already documented in root command help