GitHub Labels Template

A CLI tool to apply a curated set of GitHub labels to any repository using gh CLI. Following the Clean Labels convention by wgtechlabs.

Features

• 🏷️ 23 Curated Labels: Organized across 5 categories — type, status, community, resolution, and area
• 🚀 One Command Setup: Apply all labels to any repo with ghlt apply
• 🔍 Auto-Detect Repo: Automatically detects the current repository from git remote
• 🔄 Smart Conflict Handling: Skips existing labels by default, --force to update
• 📋 List Command: View all labels on any repo — name, color, and description at a glance
• 🧹 Wipe Command: Remove all or specific labels with a confirmation prompt
• 🚫 Apply with Exclusions: Skip specific labels or entire categories with --exclude / --exclude-category
• ✅ Pre-Flight Checks: Validates gh CLI is installed and authenticated before doing anything
• 📊 Clear Output: Structured logging powered by @wgtechlabs/log-engine with color-coded levels and emoji
• 🎨 ASCII Banner: Beautiful ANSI Shadow figlet banner with version and author info
• 🤖 AI Label Generator: Generate custom labels using GitHub Copilot — interactive pick, refine, and apply
• 🌐 Dual Runtime: Works with both npx and bunx

Quick Start

# Using npx
npx github-labels-template apply

# Using bunx
bunx github-labels-template apply

That's it. All 23 labels are applied to the current repo.

Installation

# Global install (npm)
npm install -g github-labels-template

# Global install (bun)
bun install -g github-labels-template

# Then use anywhere
ghlt apply

Prerequisites

• GitHub CLI (gh) installed and authenticated
• GitHub Copilot subscription (required for generate command only)

Usage

Apply Labels

# Apply to the current repo (auto-detected from git remote)
ghlt apply

# Apply to a specific repo
ghlt apply --repo owner/repo

# Overwrite existing labels with template values
ghlt apply --force

# Apply only a specific label
ghlt apply --label bug

# Apply specific labels (comma-separated)
ghlt apply --label "bug,enhancement"

# Apply all labels from a category
ghlt apply --category type

# Apply labels from multiple categories
ghlt apply --category "type,status"

# Combine: apply all community labels + the "bug" label
ghlt apply --category community --label bug

# Combine with force and repo
ghlt apply --category type --force --repo owner/repo

# Apply all labels except specific ones
ghlt apply --exclude "bug,enhancement"

# Apply all labels except an entire category
ghlt apply --exclude-category type

# Combine: apply all community labels except hacktoberfest
ghlt apply --category community --exclude hacktoberfest

# Include custom labels from labels-custom.json
ghlt apply --custom

# Apply only custom labels from a specific category
ghlt apply --custom --category type

List Labels

# List all labels on the current repo
ghlt list

# List labels on a specific repo
ghlt list --repo owner/repo

Generate Labels (AI)

Generate custom labels using GitHub Copilot — following the Clean Labels convention. Requires a GitHub Copilot subscription.

# Interactive label generator
ghlt generate

# Pre-select a category
ghlt generate --category type

# Generate and apply to a specific repo
ghlt generate --repo owner/repo

# Use a specific Copilot model (advanced)
ghlt generate --model gpt-4.1
ghlt generate --model claude-sonnet-4

The generator will:

1. Ask you to pick a category (type, status, community, resolution, area)
2. Ask you to describe the label you need
3. Generate 3 AI-powered suggestions following the template conventions
4. Let you pick one, refine with feedback, or regenerate
5. Save to labels-custom.json and optionally apply to a repo

Migrate Labels

Wipe all existing labels and apply the template in one step (clean slate).

# Migrate: wipe + apply (with confirmation prompt)
ghlt migrate

# Migrate a specific repo
ghlt migrate --repo owner/repo

# Skip confirmation prompt
ghlt migrate --yes

# Include custom labels in the migration
ghlt migrate --custom

Wipe Labels

# Remove all labels (with confirmation prompt)
ghlt wipe

# Remove all labels from a specific repo
ghlt wipe --repo owner/repo

# Skip confirmation prompt
ghlt wipe --yes

# Remove specific labels
ghlt wipe --label "bug,enhancement"

# Remove all labels from a category
ghlt wipe --category type

# Remove labels from multiple categories
ghlt wipe --category "type,status"

# Include custom labels in the selective wipe scope
ghlt wipe --category type --custom

Preview Landing Page

# Preview the landing page locally
ghlt preview

# Use a custom port
ghlt preview --port 8080

Common Workflows

# Clean slate with one command
ghlt migrate --yes

# Update a specific repo to match the template
ghlt apply --repo owner/repo --force

Clean Labels Convention

This project follows the Clean Labels convention by wgtechlabs — a standardized labeling format for GitHub repositories. Every label uses a consistent structure:

name · color · [Category] Description [scope]

Where scope is [issues], [PRs], or [issues, PRs].

Label Template

Type Labels

Classify what kind of work this is.

| Name | Color | Description | |------|-------|-------------| | bug | d73a4a | Something isn't working | | enhancement | 1a7f37 | New feature or improvement to existing functionality | | documentation | 0075ca | Improvements or additions to docs, README, or guides | | refactor | 8957e5 | Code improvement without changing functionality | | performance | e3795c | Optimization, speed, or resource usage improvements | | security | d4a72c | Security vulnerability or hardening |

Status Labels

Track the current workflow state.

| Name | Color | Description | |------|-------|-------------| | blocked | cf222e | Waiting on another issue, decision, or external factor | | needs triage | e16f24 | New issue — needs review and categorization | | awaiting response | 1a7ec7 | Waiting for more information from the reporter | | ready | 2da44e | Triaged and ready to be picked up |

Community Labels

Signals for open source contributors.

| Name | Color | Description | |------|-------|-------------| | good first issue | 7057ff | Good for newcomers — well-scoped and documented | | help wanted | 0e8a16 | Open for community contribution | | maintainer only | b60205 | Reserved for maintainers — not open for external contribution | | hacktoberfest | ff7518 | Participating in Hacktoberfest — open source celebration | | hacktoberfest-accepted | 16a085 | PR accepted for Hacktoberfest contribution |

Resolution Labels

Why an issue or PR was closed.

| Name | Color | Description | |------|-------|-------------| | duplicate | cfd3d7 | This issue or pull request already exists | | invalid | cfd3d7 | This doesn't seem right | | wontfix | cfd3d7 | This will not be worked on |

Area Labels

Broad software layers — universal across any project.

| Name | Color | Description | |------|-------|-------------| | core | 0052cc | Core logic, business rules, and primary functionality | | interface | 5319e7 | User-facing layer — UI, CLI, API endpoints, or SDK surface | | data | 006b75 | Database, storage, caching, or data models | | infra | e16f24 | Build system, CI/CD, deployment, config, and DevOps | | testing | 1a7f37 | Unit tests, integration tests, E2E, and test tooling |

CLI Reference

ghlt — GitHub Labels Template CLI

USAGE
  ghlt [OPTIONS] apply|wipe|migrate|generate|list|preview

OPTIONS
  -v, --version              Show version number

COMMANDS
  apply      Apply labels from the template to a repository
  wipe       Remove all or specific labels from a repository
  migrate    Wipe all existing labels and apply the template (clean slate)
  generate   Generate custom labels using AI (requires GitHub Copilot)
  list       List all labels in a repository
  preview    Preview the landing page locally in your browser

OPTIONS (apply)
  -r, --repo <owner/repo>        Target repository (default: auto-detect)
  -f, --force                    Overwrite existing labels
  -l, --label <name>             Apply specific label(s) by name (comma-separated)
  -c, --category <name>          Apply labels from specific category(ies) (comma-separated)
  -e, --exclude <name>           Exclude specific label(s) by name (comma-separated)
      --exclude-category <name>  Exclude labels from specific category(ies) (comma-separated)
      --custom                   Include custom labels from labels-custom.json

OPTIONS (list)
  -r, --repo <owner/repo>   Target repository (default: auto-detect)

OPTIONS (migrate)
  -r, --repo <owner/repo>   Target repository (default: auto-detect)
  -y, --yes                  Skip confirmation prompt
      --custom               Include custom labels from labels-custom.json

OPTIONS (generate)
  -r, --repo <owner/repo>   Target repository for optional apply step
  -c, --category <name>      Pre-select a category (type, status, community, resolution, area)
  -m, --model <model>        Copilot model to use (default: your Copilot config)

OPTIONS (wipe)
  -r, --repo <owner/repo>   Target repository (default: auto-detect)
  -y, --yes                  Skip confirmation prompt
  -l, --label <name>         Remove specific label(s) by name (comma-separated)
  -c, --category <name>      Remove labels from specific category(ies) (comma-separated)
      --custom               Include custom labels when using --label or --category

OPTIONS (preview)
  -p, --port <number>        Port to serve on (default: 3000)

Testing

This project uses the Bun test framework for testing.

# Run all tests
bun test

Contributing

Contributions are welcome! This project follows the Clean Commit convention.

License

This project is licensed under the CC0 1.0 Universal.

Author

Waren Gonzaga