gh-label-kit

README

gh-label-kit

gh-label-kit is a set of gh extension commands for GitHub label management and auto-labeling.

Installation

To install the tool, you can use the following command:

gh extension install srz-zumix/gh-label-kit

Shell Completion

Workaround Available! While gh CLI doesn't natively support extension completion, we provide a patch script that enables it.

Prerequisites: Before setting up gh-label-kit completion, ensure gh CLI completion is configured for your shell. See gh completion documentation for setup instructions.

For detailed installation instructions and setup for each shell, see the Shell Completion Guide.

Global Flags

--log-level

Set the logging level for output. Available levels: debug, info, warn, error (default: info)

gh label-kit --log-level debug <command>

--read-only

Run in read-only mode to prevent write operations. This option is useful for safely testing commands or verifying what changes would be made without actually applying them. When enabled, all API calls that would modify data (create, update, delete operations) will be blocked.

gh label-kit --read-only <command>

Commands & Usage

---

labeler: Auto-label PRs

gh label-kit labeler <pr-number...> [--repo <owner/repo>] [--config <path>] [--sync] [--dryrun] [--color <auto|always|never>] [--format <json>] [--jq <expression>] [--template <string>] [--name-only] [--no-hidden] [--ref <string>] [--skip-local-config] [--strict]

Automatically add or remove labels to GitHub Pull Requests based on changed files, branch name, PR author, and a YAML config file (default: .github/labeler.yml). Supports glob/regex patterns, extended glob patterns (extglob), author matching (including team membership), and syncLabels option for label removal. This command behaves the same as actions/labeler with additional extglob and author support.

• --color: Use color in diff output (auto|never|always, default: auto)
• --config: Path to labeler config YAML file (default: .github/labeler.yml)
  • path
  • github url (https://github.com/owner/repo[/tree/ref|/blob/ref/path])
  • actions uses format (owner/repo[/path]@ref)
• --dryrun/-n: Dry run: do not actually set labels
• --format: Output format (json)
• --jq: Filter JSON output using a jq expression
• --name-only: Output only team names
• --no-hidden: Exclude hidden files (files starting with .) from glob matching
• --ref: Git reference (branch, tag, or commit SHA) to load config from repository
• --repo/-R: Target repository in the format 'owner/repo'
• --skip-local-config: Skip loading config from local file and load from repository instead
• --strict: Treat unknown fields in config as errors instead of warnings
• --sync: Remove labels not matching any condition
• --template/-t: Format JSON output using a Go template

The labeler command uses a YAML configuration file to define labeling rules. The configuration format is compatible with actions/labeler, with additional support for author, color, description, and codeowners features.

For detailed configuration documentation, see docs/labeler-config.md.

---

repo copy: Copy labels between repositories

gh label-kit repo copy <dst-repository...> [--repo <owner/repo>] [--force]

Copy all labels from the source repository to the destination repositories. If a label already exists in the destination, it will be skipped unless --force is specified.

• --force/-f: Overwrite existing labels in the destination repository
• --repo/-R: Repository in the format 'owner/repo' (source repository)

---

repo list: List labels

gh label-kit repo list [--repo <owner/repo>] [--color <auto|always|never>] [--format <json>] [--jq <expression>] [--template <string>]

List all labels in the specified repository.

• --color: Use color in diff output (always|never|auto, default: auto)
• --format: Output format (json)
• --jq: Filter JSON output using a jq expression
• --repo/-R: Repository in the format 'owner/repo'
• --template/-t: Format JSON output using a Go template

---

repo sync: Sync label differences

gh label-kit repo sync <dst-repository...> [--repo <owner/repo>] [--force]

Sync all labels from the source repository to the destination repositories. If a label already exists in the destination, it will be updated if --force is specified.

• --force/-f: Overwrite existing labels in the destination repository
• --repo/-R: The repository in the format 'owner/repo' (source repository)

---

runner list: List GitHub Actions runner labels

gh label-kit runner list [--repo <owner/repo>] [--owner <organization>] [--format <json>] [--jq <expression>] [--template <string>]

List all GitHub Actions runner labels in the specified repository.

• --format: Output format (json)
• --jq: Filter JSON output using a jq expression
• --owner: Specify the organization name
• --repo/-R: Repository in the format 'owner/repo'
• --template/-t: Format JSON output using a Go template

---

issue add: Add label(s) to issue

gh label-kit issue add <number> <label>... [--repo <owner/repo>] [--color <auto|always|never>] [--format <json>] [--jq <expression>] [--template <string>]

Add one or more labels to a issue in the repository.

• --color: Use color in diff output (always|never|auto, default: auto)
• --format: Output format (json)
• --jq: Filter JSON output using a jq expression
• --repo/-R: Repository in the format 'owner/repo'
• --template/-t: Format JSON output using a Go template

---

issue clear: Remove all labels from issue

gh label-kit issue clear <number> [--repo <owner/repo>]

Remove all labels from a issue in the repository.

• --repo/-R: Repository in the format 'owner/repo'

---

issue list: List labels for issue

gh label-kit issue list <number> [--repo <owner/repo>] [--color <auto|always|never>] [--format <json>] [--jq <expression>] [--template <string>]

List all labels attached to a issue in the repository.

• --color: Use color in diff output (always|never|auto, default: auto)
• --format: Output format (json)
• --jq: Filter JSON output using a jq expression
• --repo/-R: Repository in the format 'owner/repo'
• --template/-t: Format JSON output using a Go template

---

issue remove: Remove label(s) from issue

gh label-kit issue remove <number> <label>... [--repo <owner/repo>] [--color <auto|always|never>] [--format <json>] [--jq <expression>] [--template <string>]

Remove one or more labels from a issue in the repository.

• --color: Use color in diff output (always|never|auto, default: auto)
• --format: Output format (json)
• --jq: Filter JSON output using a jq expression
• --repo/-R: Repository in the format 'owner/repo'
• --template/-t: Format JSON output using a Go template

---

issue search: Search issues by query

gh label-kit issue search [query...] [--repo <owner/repo>] [--owner <organization>] [--label <label>...] [--color <auto|always|never>] [--format <json>] [--jq <expression>] [--template <string>]

Search issues in the repository using a search query. The query can include label filters and other search criteria.

• --color: Use color in diff output (always|never|auto, default: auto)
• --format: Output format (json)
• --jq: Filter JSON output using a jq expression
• --label/-l: Filter issues by labels (can be specified multiple times)
• --owner: Specify the organization name
• --repo/-R: Repository in the format 'owner/repo'
• --template/-t: Format JSON output using a Go template

---

issue set: Set labels for issue (replace all)

gh label-kit issue set <number> <label>... [--repo <owner/repo>] [--color <auto|always|never>] [--format <json>] [--jq <expression>] [--template <string>]

Set (replace) all labels for a issue in the repository.

• --color: Use color in diff output (always|never|auto, default: auto)
• --format: Output format (json)
• --jq: Filter JSON output using a jq expression
• --repo/-R: Repository in the format 'owner/repo'
• --template/-t: Format JSON output using a Go template

---

discussion add: Add label(s) to discussion

gh label-kit discussion add <number> <label>... [--repo <owner/repo>] [--color <auto|always|never>] [--format <json>] [--jq <expression>] [--template <string>]

Add one or more labels to a discussion in the repository.

• --color: Use color in diff output (always|never|auto, default: auto)
• --format: Output format (json)
• --jq: Filter JSON output using a jq expression
• --repo/-R: Repository in the format 'owner/repo'
• --template/-t: Format JSON output using a Go template

---

discussion clear: Remove all labels from discussion

gh label-kit discussion clear <number> [--repo <owner/repo>]

Remove all labels from a discussion in the repository.

• --repo/-R: Repository in the format 'owner/repo'

---

discussion list: List labels for discussion

gh label-kit discussion list <number> [--repo <owner/repo>] [--color <auto|always|never>] [--format <json>] [--jq <expression>] [--template <string>]

List all labels attached to a discussion in the repository.

• --color: Use color in diff output (always|never|auto, default: auto)
• --format: Output format (json)
• --jq: Filter JSON output using a jq expression
• --repo/-R: Repository in the format 'owner/repo'
• --template/-t: Format JSON output using a Go template

---

discussion remove: Remove label(s) from discussion

gh label-kit discussion remove <number> <label>... [--repo <owner/repo>] [--color <auto|always|never>] [--format <json>] [--jq <expression>] [--template <string>]

Remove one or more labels from a discussion in the repository.

• --color: Use color in diff output (always|never|auto, default: auto)
• --format: Output format (json)
• --jq: Filter JSON output using a jq expression
• --repo/-R: Repository in the format 'owner/repo'
• --template/-t: Format JSON output using a Go template

---

discussion search: Search discussions by query

gh label-kit discussion search [query...] [--repo <owner/repo>] [--owner <organization>] [--label <label>...] [--color <auto|always|never>] [--format <json>] [--jq <expression>] [--template <string>]

Search discussions in the repository using a search query. The query can include label filters and other search criteria.

• --color: Use color in diff output (always|never|auto, default: auto)
• --format: Output format (json)
• --jq: Filter JSON output using a jq expression
• --label/-l: Filter discussions by labels (can be specified multiple times)
• --owner: Specify the organization name
• --repo/-R: Repository in the format 'owner/repo'
• --template/-t: Format JSON output using a Go template

---

discussion set: Set labels for discussion (replace all)

gh label-kit discussion set <number> <label>... [--repo <owner/repo>] [--color <auto|always|never>] [--format <json>] [--jq <expression>] [--template <string>]

Set (replace) all labels for a discussion in the repository.

• --color: Use color in diff output (always|never|auto, default: auto)
• --format: Output format (json)
• --jq: Filter JSON output using a jq expression
• --repo/-R: Repository in the format 'owner/repo'
• --template/-t: Format JSON output using a Go template

---

milestone list: List labels for milestone

gh label-kit milestone list <milestone> [--repo <owner/repo>] [--color <auto|always|never>] [--format <json>] [--jq <expression>] [--template <string>]

List all labels attached to issues and PRs in the specified milestone.

• --color: Use color in diff output (always|never|auto, default: auto)
• --format: Output format (json)
• --jq: Filter JSON output using a jq expression
• --repo/-R: Repository in the format 'owner/repo'
• --template/-t: Format JSON output using a Go template

---

skills: Manage bundled agent skills

gh label-kit skills list
gh label-kit skills <install|update|reinstall|uninstall|status> [-scope <user|repo>] [-prefix <dir>] [-dry-run] [-force]

Install and manage the agent skills bundled with gh-label-kit.

• -dry-run: Print what would happen without making changes (default: false)
• -force: Overwrite unmanaged skills (default: false)
• -prefix: Skill installation directory (overrides -scope)
• -scope: Installation scope: user (~/.agents/skills) or repo (<repo-root>/.agents/skills) (default: user)

Documentation

Overview

Copyright © 2025 srz_zumix