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](https://www.nibzard.com/ai-native)): - 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: ```json { "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: ```bash $ 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: ```json { "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 | ## Related - Existing MCP implementation: `internal/commands/mcp/serve/` - MCP annotations: `internal/mcpannotations/annotations.go` - Environment variables already documented in root command help ## References - [The Hidden Users: Designing CLI Tools for AI Agents](https://www.nibzard.com/ai-native) - [llms.txt specification](https://llmstxt.org/) - [Agentic Terminal - InfoQ](https://www.infoq.com/articles/agentic-terminal-cli-agents/) /label ~"feature::addition" ~"type::feature"