tool:
  schema_version: 1.0
  id: github-cli
  type: cli
  name: GitHub CLI
  version: 1.0.0
  description: Official GitHub command-line interface for repository management, PR operations, issue tracking, and GitHub Actions
  knowledge_strategy: declarative

  capabilities:
    - Repository management (create, clone, view)
    - Pull request operations (create, review, merge, list)
    - Issue management (create, list, view, comment)
    - GitHub Actions workflow management
    - Release management
    - Gist operations
    - Organization and team management
    - Authentication and configuration

  use_cases:
    - pr_workflow: "Create and manage pull requests from CLI"
    - issue_tracking: "Track and update issues without leaving terminal"
    - ci_monitoring: "View and manage GitHub Actions workflow runs"
    - repo_operations: "Clone, create, and manage repositories"
    - code_review: "Review and approve pull requests"
    - release_management: "Create and manage GitHub releases"

  installation:
    windows: "winget install --id GitHub.cli"
    macos: "brew install gh"
    linux: "See https://github.com/cli/cli/blob/trunk/docs/install_linux.md"

  cli_specific:
    executable: "gh"
    configuration:
      auth_check: "gh auth status"
      login: "gh auth login"
      config_file: "~/.config/gh/config.yml"
      hosts_file: "~/.config/gh/hosts.yml"

  command_groups:
    repository:
      - command: "gh repo create"
        description: "Create a new repository"
        common_flags:
          - "--public / --private"
          - "--clone"
          - "--description"

      - command: "gh repo clone"
        description: "Clone a repository"
        usage: "gh repo clone OWNER/REPO [DIRECTORY]"

      - command: "gh repo view"
        description: "View repository details"
        common_flags:
          - "--web (open in browser)"
          - "--json (output as JSON)"

    pull_request:
      - command: "gh pr create"
        description: "Create a pull request"
        common_flags:
          - "--title / -t"
          - "--body / -b"
          - "--base / -B"
          - "--draft"
          - "--web"

      - command: "gh pr list"
        description: "List pull requests"
        common_flags:
          - "--state (open, closed, merged, all)"
          - "--author"
          - "--assignee"

      - command: "gh pr view"
        description: "View a pull request"
        usage: "gh pr view [NUMBER]"
        common_flags:
          - "--web"
          - "--comments"

      - command: "gh pr merge"
        description: "Merge a pull request"
        common_flags:
          - "--merge / --squash / --rebase"
          - "--delete-branch"
          - "--auto"

    issue:
      - command: "gh issue create"
        description: "Create an issue"
        common_flags:
          - "--title / -t"
          - "--body / -b"
          - "--assignee / -a"
          - "--label / -l"

      - command: "gh issue list"
        description: "List issues"
        common_flags:
          - "--state (open, closed, all)"
          - "--author"
          - "--assignee"

      - command: "gh issue view"
        description: "View an issue"
        usage: "gh issue view [NUMBER]"

      - command: "gh issue comment"
        description: "Add a comment to an issue"
        usage: "gh issue comment NUMBER --body TEXT"

    workflow:
      - command: "gh run list"
        description: "List workflow runs"
        common_flags:
          - "--workflow"
          - "--branch"
          - "--status"

      - command: "gh run view"
        description: "View a workflow run"
        usage: "gh run view [RUN_ID]"
        common_flags:
          - "--log"
          - "--log-failed"

      - command: "gh run watch"
        description: "Watch a workflow run"
        usage: "gh run watch [RUN_ID]"

      - command: "gh workflow run"
        description: "Trigger a workflow"
        usage: "gh workflow run WORKFLOW_NAME"

    api:
      - command: "gh api"
        description: "Make authenticated GitHub API requests"
        usage: "gh api ENDPOINT [flags]"
        common_flags:
          - "--method / -X"
          - "--field / -f"
          - "--raw-field / -F"
          - "--header / -H"
        examples:
          - "gh api repos/:owner/:repo"
          - "gh api user/memberships"
          - "gh api repos/:owner/:repo/pulls/NUMBER/comments"

  best_practices:
    - "Always authenticate before using: gh auth status"
    - "Use --json flag for programmatic output"
    - "Set default repository context: gh repo set-default"
    - "Use aliases for common commands: gh alias set"
    - "Combine with jq for JSON processing: gh api | jq"
    - "Use --web flag to open things in browser"

  authentication:
    - method: "OAuth token"
      setup: "gh auth login"
      scopes: "repo, workflow, admin:org, gist"
    - method: "Personal Access Token"
      setup: "gh auth login --with-token"
      env_var: "GITHUB_TOKEN"

  integration_patterns:
    with_git:
      - "gh repo clone → git operations → gh pr create"
      - "git commit → git push → gh pr create"

    with_ci:
      - "gh run list to check status"
      - "gh run view --log-failed for debugging"
      - "gh workflow run to trigger builds"

    with_scripts:
      - "Use --json output for parsing"
      - "Check exit codes for automation"
      - "Use GITHUB_TOKEN for CI environments"

  error_handling:
    not_authenticated:
      error: "You are not logged into any GitHub hosts"
      solution: "Run 'gh auth login' to authenticate"

    insufficient_permissions:
      error: "Resource not accessible by integration"
      solution: "Check authentication scopes and repository access"

    rate_limit:
      error: "API rate limit exceeded"
      solution: "Wait for rate limit reset or use authenticated requests"

  limitations:
    - "Requires GitHub account"
    - "Rate limits apply (higher for authenticated requests)"
    - "Some operations require repository write access"
    - "Not all GitHub API features exposed via CLI"