### Build ghtkn from source using Go

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/INSTALL.md

Builds and installs the ghtkn executable binary from its source code using the Go toolchain. This method ensures you have the latest version directly from the repository.

```shell
go install github.com/suzuki-shunsuke/ghtkn/cmd/ghtkn@latest
```

--------------------------------

### Conventional Commits Example Messages

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/AGENTS.md

Provides practical examples of commit messages that follow the Conventional Commits specification. These examples demonstrate how to format messages for different types of changes, including features, fixes, documentation, and dependency updates.

```markdown
```
feat: add GitHub token management via keyring
fix: handle empty configuration file correctly
docs: add function documentation to controller package
chore(deps): update dependency aquaproj/aqua-registry to v4.403.0
```
```

--------------------------------

### Error Wrapping Example

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/AGENTS.md

Illustrates the recommended way to wrap errors in Go using `fmt.Errorf` with the `%w` verb. This preserves the original error context, aiding in debugging and error handling.

```go
```go
// Use fmt.Errorf with %w for wrapping errors
// err := fmt.Errorf("failed to process request: %w", originalErr)
```
```

--------------------------------

### ghtkn completion Command Help and Examples

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/USAGE.md

Provides help and usage examples for the `ghtkn completion` command, which generates shell completion scripts for bash, zsh, fish, and Powershell. Users can source these scripts to enable command auto-completion.

```console
$ ghtkn completion --help
NAME:
   ghtkn completion - Output shell completion script for bash, zsh, fish, or Powershell

USAGE:
   ghtkn completion

DESCRIPTION:
   Output shell completion script for bash, zsh, fish, or Powershell.
   Source the output to enable completion.

   # .bashrc
   source <(ghtkn completion bash)

   # .zshrc
   source <(ghtkn completion zsh)

   # fish
   ghtkn completion fish > ~/.config/fish/completions/ghtkn.fish

   # Powershell
   Output the script to path/to/autocomplete/ghtkn.ps1 an run it.


OPTIONS:
   --help, -h  show help

```

--------------------------------

### Download and verify ghtkn release asset with Cosign

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/INSTALL.md

Downloads a ghtkn release asset, its checksums, and signature files, then verifies them using Cosign. This method checks the authenticity of the downloaded asset by verifying the signature against the checksum file.

```shell
version=v0.1.0
checksum_file="ghtkn_checksums.txt"
asset=ghtkn_darwin_arm64.tar.gz
gh release download "$version" \
  -R suzuki-shunsuke/ghtkn \
  -p "$asset" \
  -p "$checksum_file" \
  -p "${checksum_file}.pem" \
  -p "${checksum_file}.sig"
cosign verify-blob \
  --signature "${checksum_file}.sig" \
  --certificate "${checksum_file}.pem" \
  --certificate-identity-regexp 'https://github\.com/suzuki-shunsuke/go-release-workflow/\.github/workflows/release\.yaml@.*' \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
  "$checksum_file"
cat "$checksum_file" | sha256sum -c --ignore-missing -
```

--------------------------------

### Install ghtkn with Scoop

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/INSTALL.md

Installs the ghtkn tool using the Scoop package manager. This method requires adding a custom bucket before installing the tool.

```shell
scoop bucket add suzuki-shunsuke https://github.com/suzuki-shunsuke/scoop-bucket
scoop install ghtkn
```

--------------------------------

### Download and verify ghtkn release asset with GitHub CLI

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/INSTALL.md

Downloads a specific release asset for ghtkn and verifies its integrity using GitHub CLI. This involves downloading the asset and its attestation, then verifying the attestation against the source repository and workflow.

```shell
version=v0.1.0
asset=ghtkn_darwin_arm64.tar.gz
gh release download -R suzuki-shunsuke/ghtkn "$version" -p "$asset"
gh attestation verify "$asset" \
  -R suzuki-shunsuke/ghtkn \
  --signer-workflow suzuki-shunsuke/go-release-workflow/.github/workflows/release.yaml
```

--------------------------------

### ghtkn get Command Help

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/USAGE.md

Explains the `ghtkn get` command, used to output a GitHub App User Access Token to standard output. Supports specifying output format and minimum expiration duration.

```console
$ ghtkn get --help
NAME:
   ghtkn get - Output a GitHub App User Access Token to stdout

USAGE:
   ghtkn get [arguments...]

OPTIONS:
   --log-level string                  Log level (debug, info, warn, error) [$GHTKN_LOG_LEVEL]
   --config string, -c string          configuration file path [$GHTKN_CONFIG]
   --format string, -f string          output format (json) [$GHTKN_OUTPUT_FORMAT]
   --min-expiration string, -m string  minimum expiration duration (e.g. 1h, 30m, 30s) [$GHTKN_MIN_EXPIRATION]
   --help, -h                          show help

```

--------------------------------

### Install ghtkn with Homebrew

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/INSTALL.md

Installs the ghtkn tool using the Homebrew package manager. This is a straightforward installation method for macOS and Linux users.

```shell
brew install suzuki-shunsuke/ghtkn/ghtkn --cask
```

--------------------------------

### Install ghtkn with aqua

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/INSTALL.md

Installs the ghtkn tool using the aqua package manager. This method requires aqua version v4.407.0 or later and uses a global install command.

```shell
aqua g -i suzuki-shunsuke/ghtkn
```

--------------------------------

### Download and verify ghtkn release asset with slsa-verifier

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/INSTALL.md

Downloads a ghtkn release asset and verifies it using slsa-verifier. This process involves downloading the asset and its provenance data, then using slsa-verifier to confirm the artifact's origin and build process.

```shell
version=v0.1.0
asset=ghtkn_darwin_arm64.tar.gz
gh release download -R suzuki-shunsuke/ghtkn "$version" -p "$asset" -p multiple.intoto.jsonl
slsa-verifier verify-artifact "$asset" \
  --provenance-path multiple.intoto.jsonl \
  --source-uri github.com/suzuki-shunsuke/ghtkn \
  --source-tag "$version"
```

--------------------------------

### ghtkn Configuration File Example

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/README.md

An example of the ghtkn configuration file (ghtkn.yaml). It specifies the GitHub App name and its corresponding Client ID. The Client ID is not a secret and can be stored in plain text.

```yaml
apps:
  - name: suzuki-shunsuke/none
    client_id: xxx # Mandatory. GitHub App Client ID
```

--------------------------------

### Conventional Commits Format Example

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/AGENTS.md

Illustrates the standard format for commit messages in the ghtkn project, adhering to the Conventional Commits specification. This includes the type, optional scope, description, and optional body and footers.

```markdown
```
<type>[optional scope]: <description>

[optional body]

[optional footer(s)]
```
```

--------------------------------

### Controlling Token Regeneration with Minimum Expiration

Source: https://context7.com/suzuki-shunsuke/ghtkn/llms.txt

Demonstrates how to use the `ghtkn get` command with the `-m` flag or the `GHTKN_MIN_EXPIRATION` environment variable to specify the minimum required validity period for a token, forcing regeneration if the cached token does not meet the criteria.

```bash
# Default: Return cached token if not expired
ghtkn get

# Require at least 1 hour of validity
ghtkn get -m 1h

# Require at least 50 minutes (useful for long-running scripts)
ghtkn get -m 50m

# Force regeneration (request more than 8-hour max validity)
ghtkn get -m 9h

# Set via environment variable
export GHTKN_MIN_EXPIRATION=10m
ghtkn get
```

--------------------------------

### Initialize GH Token and Execute gh Command (Shell)

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/README.md

This script checks if GH_TOKEN or GITHUB_TOKEN environment variables are set. If not, it retrieves a token using 'ghtkn get' and exports it. Finally, it executes the 'gh' command with provided arguments, ensuring an absolute path is used to prevent infinite loops.

```shell
if [ -z "${GH_TOKEN:-}" ] && [ -z "${GITHUB_TOKEN:-}" ]; then
  GH_TOKEN="$(ghtkn get)"
  export GH_TOKEN
fi

exec /opt/homebrew/bin/gh "$@"
```

--------------------------------

### Configure direnv for Directory-Specific GHTKN App

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/README.md

Provides examples of `.envrc` files used with `direnv` to automatically set the `GHTKN_APP` environment variable based on the current directory. This enables seamless switching of the active GitHub App as you navigate between different project directories.

```sh
source_up

export GHTKN_APP=suzuki-shunsuke/write
```

--------------------------------

### Create GitHub Issue using ghtkn Token

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/README.md

Demonstrates how to create a GitHub issue using a token obtained from ghtkn. It sets the GH_TOKEN environment variable and uses the GitHub CLI to create the issue. Requires appropriate GitHub App permissions and installation.

```sh
REPO=suzuki-shunsuke/ghtkn # Please change this to your public repository
env GH_TOKEN=$(ghtkn get) gh issue create -R "$REPO" --title "Hello, ghtkn" --body "This is created by ghtkn"
```

--------------------------------

### Set ghtkn Output Format via Environment Variable

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/README.md

Explains how to configure the output format for the `ghtkn get` command using the `GHTKN_OUTPUT_FORMAT` environment variable. This allows users to specify `json` output for easier programmatic consumption of access token information.

```sh
export GHTKN_OUTPUT_FORMAT=json
```

--------------------------------

### Get GitHub User Access Token

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/README.md

Retrieves a GitHub User Access Token. This command initiates the Device Flow, opening a browser for user authorization. Subsequent calls reuse the token stored in the secret manager.

```sh
ghtkn get
```

--------------------------------

### Configure Multiple GitHub Apps in ghtkn Configuration

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/README.md

Illustrates the YAML configuration for defining multiple GitHub Apps within ghtkn. This allows ghtkn to manage and switch between different applications, each potentially having distinct permissions or associated with different organizations. The example includes a default app with no permissions.

```yaml
apps:
  - name: suzuki-shunsuke/none
    client_id: xxx
```

--------------------------------

### Integrate ghtkn Go SDK for Token Management

Source: https://context7.com/suzuki-shunsuke/ghtkn/llms.txt

This Go code demonstrates how to use the ghtkn-go-sdk to obtain or create GitHub access tokens. It shows client initialization, setting input parameters like configuration file path and application name, and retrieving an access token along with associated application details. Error handling for client creation and token retrieval is included.

```go
package main

import (
    "context"
    "fmt"
    "log"
    "log/slog"
    "os"
    "time"

    "github.com/suzuki-shunsuke/ghtkn-go-sdk/ghtkn"
)

func main() {
    ctx := context.Background()
    logger := slog.New(slog.NewTextHandler(os.Stderr, nil))

    // Create ghtkn client
    client, err := ghtkn.NewClient()
    if err != nil {
        log.Fatal(err)
    }

    // Configure input parameters
    input := &ghtkn.InputGet{
        ConfigFilePath: "", // Use default config path
        AppName:        "", // Use first app from config
        MinExpiration:  30 * time.Minute,
    }

    // Get or create access token
    token, app, err := client.Get(ctx, logger, input)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("App: %s\n", app.Name)
    fmt.Printf("Token: %s\n", token.AccessToken)
    fmt.Printf("Expires: %s\n", token.ExpiresAt)
}
```

--------------------------------

### ghtkn init Command Help

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/USAGE.md

Provides help for the `ghtkn init` command, which is used to create the `ghtkn.yaml` configuration file if it does not already exist. It accepts standard global options.

```console
$ ghtkn init --help
NAME:
   ghtkn init - Create ghtkn.yaml if it doesn't exist

USAGE:
   ghtkn init [arguments...]

OPTIONS:
   --log-level string          Log level (debug, info, warn, error) [$GHTKN_LOG_LEVEL]
   --config string, -c string  configuration file path [$GHTKN_CONFIG]
   --help, -h                  show help

```

--------------------------------

### Build Project Command

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/AGENTS.md

Displays the command used to build the ghtkn project. This command compiles the Go source code into an executable binary.

```bash
```bash
# Build the project
go build ./cmd/ghtkn
```
```

--------------------------------

### Running All Tests Command

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/AGENTS.md

Provides the command to run all tests in the project, which is a crucial step before committing code. This command ensures code integrity and functionality.

```bash
```bash
# Run all tests: cmdx t or go test ./...
```
```

--------------------------------

### Running Specific Package Tests

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/AGENTS.md

Illustrates how to run tests for a specific package within the ghtkn project. This is useful for targeted testing during development.

```bash
```bash
# Run specific package tests: go test ./pkg/controller/initcmd
```
```

--------------------------------

### Generic Command Wrapper Script with GITHUB_TOKEN Injection

Source: https://context7.com/suzuki-shunsuke/ghtkn/llms.txt

Provides a flexible wrapper script 'ghtkn-wrap' that injects a ghtkn-generated token into the GITHUB_TOKEN environment variable before executing any specified command. Also includes 'ghtkn-gen-wrap' to automatically create specific command wrappers.

```bash
# ghtkn-wrap: Wraps any command with GITHUB_TOKEN injection
#!/usr/bin/env bash
set -eu
cmd=$1
shift
GITHUB_TOKEN="$(ghtkn get)"
export GITHUB_TOKEN
exec "$cmd" "$@"

# Usage
ghtkn-wrap terraform plan
ghtkn-wrap gh pr list

# ghtkn-gen-wrap: Generate wrapper scripts for specific commands
ghtkn-gen-wrap /opt/homebrew/bin/gh
# Creates ~/bin/gh that auto-injects token
```

--------------------------------

### ghtkn CLI Help and Global Options

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/USAGE.md

Displays the main help message for the ghtkn CLI, listing available commands and global options. Global options like log level and configuration file path can be applied to all commands.

```console
$ ghtkn --help
NAME:
   ghtkn - Create GitHub App User Access Tokens for secure local development. https://github.com/suzuki-shunsuke/ghtkn

USAGE:
   ghtkn [global options] [command [command options]]

VERSION:
   0.2.4

COMMANDS:
   init            Create ghtkn.yaml if it doesn't exist
   git-credential  Git Credential Helper
   get             Output a GitHub App User Access Token to stdout
   version         Show version
   help, h         Shows a list of commands or help for one command
   completion      Output shell completion script for bash, zsh, fish, or Powershell

GLOBAL OPTIONS:
   --log-level string          Log level (debug, info, warn, error) [$GHTKN_LOG_LEVEL]
   --config string, -c string  configuration file path [$GHTKN_CONFIG]
   --help, -h                  show help
   --version, -v               print the version

```

--------------------------------

### Configure ghtkn.yaml for GitHub Apps

Source: https://context7.com/suzuki-shunsuke/ghtkn/llms.txt

This snippet shows how to configure the ghtkn.yaml file to manage multiple GitHub Apps with varying permission levels. It demonstrates setting up apps for no permissions, read-only, write, and full administrative access, including specifying client IDs and optional Git owner details.

```yaml
# ghtkn.yaml - Multiple apps with different permissions
apps:
  # No permissions - read public repos, avoid rate limits
  - name: my-org/none
    client_id: Iv1.aaaaaaaaaaaaaaaa

  # Read-only permissions
  # GitHub App: contents:read, metadata:read
  - name: my-org/read
    client_id: Iv1.bbbbbbbbbbbbbbbb

  # Write permissions for commits and PRs
  # GitHub App: contents:write, pull_requests:write
  - name: my-org/write
    client_id: Iv1.cccccccccccccccc
    git_owner: my-org  # Use for git operations

  # Full permissions for admin tasks
  # GitHub App: administration:write, contents:write, etc.
  - name: my-org/admin
    client_id: Iv1.dddddddddddddddd
```

--------------------------------

### Initialize ghtkn Configuration

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/README.md

Initializes the ghtkn configuration file. The location of the file depends on the operating system. This command sets up the basic structure for defining GitHub Apps.

```sh
ghtkn init
```

--------------------------------

### Code Validation Command (go vet)

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/AGENTS.md

Demonstrates the command used to validate Go code in the ghtkn project. This command runs `go vet ./...` to identify common mistakes and potential issues in the codebase.

```bash
```bash
cmdx v
```
```

--------------------------------

### Generating Test Coverage

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/AGENTS.md

Shows the command to generate a test coverage report for the ghtkn project. This helps in identifying areas of the code that are not adequately covered by tests.

```bash
```bash
# Generate coverage: ./scripts/coverage.sh
```
```

--------------------------------

### Directory-Based App Switching with direnv

Source: https://context7.com/suzuki-shunsuke/ghtkn/llms.txt

Utilizes direnv to automatically set the GHTKN_APP environment variable based on the current working directory, allowing different GitHub Apps to be used for different projects.

```bash
# ~/repos/src/github.com/suzuki-shunsuke/.envrc
source_up
export GHTKN_APP=suzuki-shunsuke/write

# ~/repos/src/github.com/aquaproj/.envrc
source_up
export GHTKN_APP=aquaproj/write

# Commands automatically use the correct app based on current directory
cd ~/repos/src/github.com/suzuki-shunsuke/ghtkn
ghtkn get  # Uses suzuki-shunsuke/write app
```

--------------------------------

### Specify GitHub App via Command Line or Environment Variable

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/README.md

Demonstrates how to select a specific GitHub App for use with ghtkn, either by directly specifying the app name on the command line or by setting the GHTKN_APP environment variable. This allows for flexible management of different apps for different purposes or organizations.

```sh
ghtkn get suzuki-shunsuke/write

export GHTKN_APP=aquaproj/write
```

--------------------------------

### Troubleshoot macOS Git Credential Helper with ghtkn

Source: https://context7.com/suzuki-shunsuke/ghtkn/llms.txt

This bash snippet addresses issues with the macOS osxkeychain credential helper conflicting with ghtkn. It provides commands to check the current credential helper configuration, and demonstrates how to reset and configure the gitconfig file to use ghtkn's credential helper. It also includes steps for verifying the fix using trace logging.

```bash
# Check which credential helpers are configured
git config --get-all --show-origin credential.helper
# Output shows:
# file:/Library/Developer/CommandLineTools/usr/share/git-core/gitconfig   osxkeychain
# file:/Users/username/.gitconfig   !ghtkn git-credential

# Fix: Reset helper list and set ghtkn
# ~/.gitconfig
[credential]
    helper = ""
    helper = !ghtkn git-credential

# Verify with trace logging
GIT_TRACE=1 GIT_CURL_VERBOSE=1 git push origin main
# Should show: trace: run_command: ghtkn git-credential get
```

--------------------------------

### Injecting ghtkn Tokens into GitHub CLI Commands

Source: https://context7.com/suzuki-shunsuke/ghtkn/llms.txt

Demonstrates how to use ghtkn to obtain a GitHub token and inject it into the GH_TOKEN environment variable for various GitHub CLI operations like creating issues, pull requests, listing issues, and making API calls.

```bash
# Single command with token injection
env GH_TOKEN=$(ghtkn get) gh issue create -R owner/repo --title "Hello" --body "Created via ghtkn"

# Create pull request
env GH_TOKEN=$(ghtkn get) gh pr create --title "Feature" --body "Description"

# List issues
env GH_TOKEN=$(ghtkn get) gh issue list -R owner/repo

# API calls
env GH_TOKEN=$(ghtkn get) gh api /user
```

--------------------------------

### Run ghtkn Locally Command

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/AGENTS.md

Provides the command to run the ghtkn application locally. This is useful for development and testing purposes.

```bash
```bash
# Run ghtkn locally
go run ./cmd/ghtkn run
```
```

--------------------------------

### Check Git Credential Helper Configuration (Shell)

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/README.md

This command retrieves all configured Git credential helpers, including their origin. It's used to verify which credential helpers are active and from which configuration files they are set.

```shell
git config --get-all --show-origin credential.helper
```

--------------------------------

### ghtkn Environment Variables for Runtime Configuration

Source: https://context7.com/suzuki-shunsuke/ghtkn/llms.txt

Optional environment variables to configure ghtkn's runtime behavior, including log level, output format, app selection, minimum token expiration, and config file location.

```bash
# Set log level (debug, info, warn, error)
export GHTKN_LOG_LEVEL=debug

# Set output format (json for structured output)
export GHTKN_OUTPUT_FORMAT=json

# Specify which app to use
export GHTKN_APP=my-org/admin

# Set minimum token expiration (regenerate if less remaining)
export GHTKN_MIN_EXPIRATION=30m

# Override config file location
export GHTKN_CONFIG=/custom/path/ghtkn.yaml
```

--------------------------------

### Git Credential Helper Configuration (INI)

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/README.md

This INI configuration snippet sets up Git's credential helper. The first 'helper =' line is crucial for unsetting any previously configured helpers, ensuring that '!ghtkn git-credential' is the active helper.

```ini
[credential]
	helper =
	helper = !ghtkn git-credential
```

--------------------------------

### ghtkn version Command Help

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/USAGE.md

Shows help for the `ghtkn version` command, which displays the current version of the ghtkn tool. It includes an option to output the version information in JSON format.

```console
$ ghtkn version --help
NAME:
   ghtkn version - Show version

USAGE:
   ghtkn version

OPTIONS:
   --json, -j  Output version in JSON format
   --help, -h  show help

```

--------------------------------

### Enable Debug Logging

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/AGENTS.md

Demonstrates how to enable debug logging for the ghtkn application by setting the `GHTKN_LOG_LEVEL` environment variable. This is helpful for troubleshooting and understanding application behavior.

```bash
```bash
export GHTKN_LOG_LEVEL=debug
```
```

--------------------------------

### ghtkn.yaml Configuration for GitHub Apps

Source: https://context7.com/suzuki-shunsuke/ghtkn/llms.txt

Defines GitHub Apps for ghtkn, specifying their names, client IDs, and optional git owner for credential routing. Supports default, owner-specific, read-only, and organization apps.

```yaml
apps:
  # Default app (used when no app is specified)
  - name: suzuki-shunsuke/none
    client_id: Iv1.aaaaaaaaaaaaaaaa

  # App with write permissions for specific owner
  - name: suzuki-shunsuke/write
    client_id: Iv1.bbbbbbbbbbbbbbbb
    git_owner: suzuki-shunsuke  # Used for Git credential helper routing

  # Read-only app (no git_owner - won't be used for git push)
  - name: suzuki-shunsuke/read-only
    client_id: Iv1.cccccccccccccccc

  # Organization app
  - name: aquaproj/write
    client_id: Iv1.dddddddddddddddd
    git_owner: aquaproj
```

--------------------------------

### Code Testing Command

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/AGENTS.md

Shows the command to execute all tests within the ghtkn project. This ensures that all functionalities are working as expected before committing changes.

```bash
```bash
cmdx t
```
```

--------------------------------

### Shell Script Wrapper for GitHub Token Management

Source: https://context7.com/suzuki-shunsuke/ghtkn/llms.txt

A wrapper script designed to be placed in the user's PATH (e.g., ~/bin/gh) that checks for existing GitHub tokens and injects one from ghtkn if necessary before executing the actual 'gh' command.

```bash
#!/usr/bin/env bash
# Save as ~/bin/gh and chmod +x ~/bin/gh

set -eu

# Use existing token if set, otherwise get from ghtkn
if [ -z "${GH_TOKEN:-}" ] && [ -z "${GITHUB_TOKEN:-}" ]; then
  GH_TOKEN="$(ghtkn get)"
  export GH_TOKEN
fi

# Execute actual gh command (use absolute path to avoid infinite loop)
exec /opt/homebrew/bin/gh "$@"

# Alternative: Use aqua exec if gh is managed by aqua
# exec aqua exec -- gh "$@"
```

--------------------------------

### Checking Token Validity via GitHub API

Source: https://context7.com/suzuki-shunsuke/ghtkn/llms.txt

Illustrates how to verify if an access token is currently valid by making a simple API call to the `/user` endpoint using the GitHub CLI, with the token set in the GH_TOKEN environment variable.

```bash
# Check if token is valid
env GH_TOKEN=$GITHUB_TOKEN gh api \
  -H "Accept: application/vnd.github+json" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  /user
```

--------------------------------

### Generate JSON Schema Command

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/AGENTS.md

Shows the command to generate JSON schemas for the ghtkn project. This is useful for validating configuration files and data structures.

```bash
```bash
# Generate JSON schema
cmdx js
```
```

--------------------------------

### Troubleshoot Git Credential Helper on macOS (Shell)

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/README.md

This command enables trace logging for Git and cURL, which is useful for diagnosing issues with the Git credential helper on macOS. It helps in identifying if 'git-credential-osxkeychain' is being used instead of ghtkn.

```shell
GIT_TRACE=1 GIT_CURL_VERBOSE=1 git push origin
```

--------------------------------

### ghtkn git-credential Command Help

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/USAGE.md

Details the `ghtkn git-credential` command, which functions as a Git credential helper. It allows for specifying a minimum token expiration duration.

```console
$ ghtkn git-credential --help
NAME:
   ghtkn git-credential - Git Credential Helper

USAGE:
   ghtkn git-credential [arguments...]

OPTIONS:
   --log-level string                  Log level (debug, info, warn, error) [$GHTKN_LOG_LEVEL]
   --config string, -c string          configuration file path [$GHTKN_CONFIG]
   --min-expiration string, -m string  minimum expiration duration (e.g. 1h, 30m, 30s) [$GHTKN_MIN_EXPIRATION]
   --help, -h                          show help

```

--------------------------------

### Execute gh Command via aqua (Shell)

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/README.md

This command demonstrates how to execute the 'gh' command using 'aqua exec', which is useful for managing commands handled by the aqua package manager. It ensures the 'gh' command is run within the aqua environment.

```shell
exec aqua exec -- gh "$@"
```

--------------------------------

### Resolve ghtkn Background Process Token Issues

Source: https://context7.com/suzuki-shunsuke/ghtkn/llms.txt

This bash snippet provides a solution for scenarios where ghtkn runs in background processes and the device code prompt is not visible. It outlines steps to cancel any running background tasks, manually authenticate in the foreground to cache the token, and then re-run the background process, ensuring it uses the cached token without requiring interactive authentication.

```bash
# Problem: Device code not visible when ghtkn runs in background
# Solution: Pre-authenticate in foreground before running background task

# Step 1: Cancel background process
# Step 2: Authenticate manually
ghtkn get >/dev/null

# Step 3: Re-run your background process
# Token is now cached and won't require interactive authentication
```

--------------------------------

### Enable HTTP Path for GitHub Apps (Shell)

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/README.md

This command configures Git to use the HTTP path for credential helpers, which is necessary when switching GitHub Apps based on the repository owner. It ensures that the correct app is used for authentication.

```shell
git config --global credential.useHttpPath true
```

--------------------------------

### Make Scripts Executable (Shell)

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/README.md

This command changes the permissions of a script file, making it executable. It's a standard Unix/Linux command used to grant execute permissions to a file, typically located in a user's bin directory.

```shell
chmod +x ~/bin/gh
```

--------------------------------

### Configure ghtkn as Git Credential Helper (Shell)

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/README.md

This command configures ghtkn to act as a Git credential helper. It uses a shell command substitution to tell Git to use '!ghtkn git-credential' for retrieving credentials. This is essential for automating Git operations that require authentication.

```shell
git config --global credential.helper '!ghtkn git-credential'
```

--------------------------------

### Configure GitHub App for Repository Owner (YAML)

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/README.md

This YAML configuration snippet defines a GitHub App and associates it with a specific repository owner ('suzuki-shunsuke'). This allows ghtkn to use the specified app for authentication when interacting with repositories owned by 'suzuki-shunsuke'.

```yaml
apps:
  - name: suzuki-shunsuke/write
    client_id: xxx
    git_owner: suzuki-shunsuke # Using this app if the repository owner is suzuki-shunsuke
```

--------------------------------

### Set Minimum Access Token Expiration Duration

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/README.md

Shows how to ensure that the retrieved GitHub access token has a minimum validity period. This is useful for long-running processes that might otherwise encounter an expired token mid-execution. The duration can be specified via a command-line flag or an environment variable.

```sh
ghtkn get -m 1h

export GHTKN_MIN_EXPIRATION=10m
```

--------------------------------

### Generate GitHub CLI OAuth App Access Token

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/README.md

This command generates an access token for the GitHub CLI OAuth App. It's a convenient way to authenticate with GitHub CLI without needing to create Personal Access Tokens. This method is useful for accessing resources across multiple users or organizations.

```shell
-H "Accept: application/vnd.github+json" \
-H "X-GitHub-Api-Version: 2022-11-28" \
/user
```

--------------------------------

### Set ghtkn Log Level via Environment Variable

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/README.md

Demonstrates how to control the verbosity of ghtkn's logging output by setting the `GHTKN_LOG_LEVEL` environment variable. This allows users to choose between different levels such as `debug`, `info`, `warn`, and `error` for troubleshooting or reducing log noise.

```sh
export GHTKN_LOG_LEVEL=debug
```

--------------------------------

### Wrap GitHub CLI with ghtkn Token (Shell Function)

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/README.md

A shell function to wrap the GitHub CLI (gh). It automatically injects the ghtkn-generated token into the GH_TOKEN environment variable for all gh commands, ensuring authenticated requests.

```sh
gh() {
    env GH_TOKEN=$(ghtkn get) command gh "$@" # Be careful to use 'command' to avoid infinite loops
}
```

--------------------------------

### Shell Function Wrapper for Automatic GH Token Injection

Source: https://context7.com/suzuki-shunsuke/ghtkn/llms.txt

A shell function that can be added to shell configuration files (like ~/.bashrc or ~/.zshrc) to automatically inject ghtkn tokens into the GH_TOKEN environment variable for all subsequent 'gh' commands.

```bash
# Add to ~/.bashrc or ~/.zshrc
gh() {
    env GH_TOKEN=$(ghtkn get) command gh "$@"
}

# Usage (token automatically injected)
gh issue list
gh pr create --title "Feature"
gh api /repos/owner/repo
```

--------------------------------

### Revoke User Access Token with GitHub Actions

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/README.md

This workflow revokes a user's access token using the GitHub API. It requires the access token to revoke and uses client ID and secret stored as GitHub secrets. The `gh api` command is used for initial validation, and `curl` is used for the revocation call.

```yaml
---
name: Revoke a User Access Token
run-name: Revoke a User Access Token (${{github.actor}})
on:
  workflow_dispatch:
    inputs:
      access_token:
        description: 'The access token to revoke'
        required: true
        type: string
jobs:
  revoke:
    timeout-minutes: 10
    runs-on: ubuntu-24.04
    permissions: {}
    steps:
      - name: Check if the access token is available
        # This step is optional.
        continue-on-error: true # Continue even if the access token is unavailable
        env:
          GH_TOKEN: ${{inputs.access_token}} # GitHub Actions automatically masks access tokens
        run: |
          gh api \
            -H "Accept: application/vnd.github+json" \
            -H "X-GitHub-Api-Version: 2022-11-28" \
            /user
      - name: Revoke the access token
        env:
          GH_TOKEN: ${{inputs.access_token}} # GitHub Actions automatically masks access tokens
          CLIENT_ID: ${{secrets.CLIENT_ID}}
          CLIENT_SECRET: ${{secrets.CLIENT_SECRET}}
        run: |
          curl -L \
            -X DELETE \
            -H "Accept: application/vnd.github+json" \
            -u "${CLIENT_ID}:${CLIENT_SECRET}" \
            -H "X-GitHub-Api-Version: 2022-11-28" \
            "https://api.github.com/applications/${CLIENT_ID}/token" \
            -d '{"access_token":"'"${GH_TOKEN}"'"}'

```

--------------------------------

### Conventional Commits Common Types

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/AGENTS.md

Lists the common types used in commit messages for the ghtkn project, following the Conventional Commits specification. Each type signifies a different category of change, such as new features, bug fixes, documentation updates, or refactoring.

```markdown
```
- feat: A new feature
- fix: A bug fix
- docs: Documentation only changes
- style: Changes that do not affect the meaning of the code
- refactor: A code change that neither fixes a bug nor adds a feature
- test: Adding missing tests or correcting existing tests
- chore: Changes to the build process or auxiliary tools
- ci: Changes to CI configuration files and scripts
```
```

--------------------------------

### Revoke User Access Token for Multiple GitHub Apps

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/README.md

This workflow revokes a user's access token for a specific GitHub App, dynamically selecting client ID and secret from GitHub Environment Secrets based on the provided app name. It includes steps to construct secret names and then uses `curl` to revoke the token.

```yaml
---
name: Revoke a User Access Token
run-name: Revoke a User Access Token (${{github.actor}}/${{inputs.app_name}})
on:
  workflow_dispatch:
    inputs:
      app_name:
        description: GitHub App name
        required: true
        type: choice
        default: write
        options: # PLEASE CHANGE
          - none
          - read
          - write
          - full
      access_token:
        description: 'The access token to revoke'
        required: true
        type: string
jobs:
  revoke:
    timeout-minutes: 10
    runs-on: ubuntu-24.04
    permissions: {}
    environment: main
    steps:
      - name: Check if the access token is available
        # This step is optional.
        continue-on-error: true # Continue even if the access token is unavailable
        env:
          GH_TOKEN: ${{inputs.access_token}} # GitHub Actions automatically masks access tokens
        run: |
          gh api \
            -H "Accept: application/vnd.github+json" \
            -H "X-GitHub-Api-Version: 2022-11-28" \
            /user
      - name: Choose the client id and client secret
        id: secret_names
        env:
          APP_NAME: ${{inputs.app_name}}
        run: |
          UPPER_APP_NAME=$(echo "$APP_NAME" | tr '[:lower:]' '[:upper:]')
          echo CLIENT_ID_NAME="CLIENT_ID_${UPPER_APP_NAME}" >> "$GITHUB_OUTPUT"
          echo CLIENT_SECRET_NAME="CLIENT_SECRET_${UPPER_APP_NAME}" >> "$GITHUB_OUTPUT"
      - name: Revoke the access token
        env:
          GH_TOKEN: ${{inputs.access_token}} # GitHub Actions automatically masks access tokens
          CLIENT_ID: ${{secrets[steps.secret_names.outputs.CLIENT_ID_NAME]}}
          CLIENT_SECRET: ${{secrets[steps.secret_names.outputs.CLIENT_SECRET_NAME]}}
        run: |
          curl -L \
            -X DELETE \
            -H "Accept: application/vnd.github+json" \
            -u "${CLIENT_ID}:${CLIENT_SECRET}" \
            -H "X-GitHub-Api-Version: 2022-11-28" \
            "https://api.github.com/applications/${CLIENT_ID}/token" \
            -d '{"access_token":"'"${GH_TOKEN}"'"}'
      - name: Check if the access token has been revoked
        # This step is optional.
        continue-on-error: true # Continue even if the access token is unavailable
        env:
          GH_TOKEN: ${{inputs.access_token}} # GitHub Actions automatically masks access tokens
        run: |
          gh api \

```

--------------------------------

### Revoking Leaked GitHub Tokens

Source: https://context7.com/suzuki-shunsuke/ghtkn/llms.txt

Provides three methods for revoking leaked GitHub tokens: through the GitHub App settings UI, via a `curl` command using the GitHub API (requires client secret), and through user settings for authorized GitHub Apps.

```bash
# Method 1: Revoke via GitHub App settings page
# Navigate to: GitHub App Settings > "Revoke all user tokens"

# Method 2: Revoke specific token via API (requires client_secret)
curl -L -X DELETE \
  -H "Accept: application/vnd.github+json" \
  -u "${CLIENT_ID}:${CLIENT_SECRET}" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  "https://api.github.com/applications/${CLIENT_ID}/token" \
  -d '{"access_token":"'"${LEAKED_TOKEN}"'"}'

# Method 3: Revoke app authorization from user settings
# Navigate to: GitHub Settings > Applications > Authorized GitHub Apps > Revoke
```

--------------------------------

### Revoke GitHub Access Token using GitHub API

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/README.md

This snippet demonstrates how to revoke a GitHub access token by making an API call to the '/user' endpoint. It requires setting the 'GH_TOKEN' environment variable with the leaked token and uses the 'gh api' command. The API call verifies the token's validity.

```shell
env GH_TOKEN=$LEAKED_GITHUB_TOKEN gh api \
  -H "Accept: application/vnd.github+json" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  /user
```

--------------------------------

### Renew GitHub App Access Token using ghtkn

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/README.md

This command renews the access token for a GitHub App process when the device flow is not displayed in the terminal. It's used to resolve issues where background processes prevent the device code from appearing, ensuring the token is updated for continued operation.

```shell
ghtkn get >/dev/null
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.