ghtkn

https://github.com/suzuki-shunsuke/ghtkn
Admin
ghtkn is a secure GitHub token manager that generates short-lived (8-hour) user access tokens from...
Tokens:41,466
Snippets:607
Trust Score:9.6
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install ghtkn with Go

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

Build and install the binary directly from the source repository using Go.

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

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

### Clipboard Integration Example

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/_autodocs/api-reference/clipboard.md

Demonstrates how to create the clipboard function and inject it into the SDK client.

```go
copyFunc := clipboard.New()

// In the SDK client setup:
client.SetCopyOnetimeCodeToClipboard(copyFunc)

// When device flow generates a one-time code, the SDK calls:
if err := copyFunc(ctx, "ABC-123-DEF"); err != nil {
	log.Printf("Failed to copy code to clipboard: %v", err)
}
```

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

### View shell completion example

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

Example of how shell completion works for ghtkn commands.

```console
$ ghtkn get <TAB>
my-app  work-app
```

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

### Install ghtkn with Scoop

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

Add the custom bucket and install ghtkn using Scoop.

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

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

### Agent Backend Setup

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

Commands to initialize and authenticate the agent on a CI server.

```bash
# Start agent as systemd service (or in container entrypoint)
ghtkn agent &

# Authenticate once (interactively, or via bootstrap token)
ghtkn auth -a ci-org/ci-app

# Lock agent when not needed
ghtkn agent lock
```

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

### Install ghtkn with Homebrew

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

Use this command to install the ghtkn binary via Homebrew.

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

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

### Advanced ghtkn exec Examples

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/_autodocs/cli-commands.md

Examples demonstrating token expiration requirements and error handling configurations.

```bash
# Run gh with default GITHUB_TOKEN
ghtkn exec -- gh pr view

# Run gh with custom env var
ghtkn exec -e GH_TOKEN -- gh pr view

# Use specific app
ghtkn exec -e GH_TOKEN:my-org/read -- gh pr list

# Multiple apps in one command
ghtkn exec \
  -e GITHUB_TOKEN:org1/app \
  -e SECONDARY_TOKEN:org2/app \
  -- bash deploy.sh

# Require token valid for 1 hour
ghtkn exec -m 1h -- terraform plan

# Continue even if token retrieval fails
ghtkn exec --continue-on-error -e MAYBE_TOKEN:optional-app -- gh issue create
```

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

### Install ghtkn with aqua

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

Install ghtkn using the aqua package manager.

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

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

### Install ghtkn skill

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

Use the GitHub CLI to install the ghtkn skill for your coding agent.

```sh
gh skill install suzuki-shunsuke/ghtkn ghtkn
```

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

### Start ghtkn agent

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

Launch the agent in the foreground, listening on a Unix domain socket.

```console
$ ghtkn agent start --help
```

```console
$ ghtkn agent start
```

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

### ghtkn get command examples

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

Various ways to invoke the ghtkn get command to retrieve tokens.

```console
$ ghtkn get
```

```console
$ ghtkn get my-app
```

```console
$ ghtkn get -f json my-app
```

```console
$ ghtkn get -m 1h my-app
```

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

### Initialize Input

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/_autodocs/api-reference/controller-auth.md

Creates an Input instance with default production values, including SDK client setup.

```go
func NewInput() (*Input, error)
```

```go
input, err := auth.NewInput()
if err != nil {
	return fmt.Errorf("create controller input: %w", err)
}
```

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

### Configuration Precedence Example

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

Demonstrates how command-line flags override environment variables and configuration file settings.

```bash
# Config file has: clipboard.enable: true
# Environment: export GHTKN_CLIPBOARD=false
# Command-line: ghtkn auth --clipboard

# Result: --clipboard (true) overrides GHTKN_CLIPBOARD (false) which overrides config (true)
# Final: clipboard is enabled
```

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

### ghtkn exec Usage Examples

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/_autodocs/cli-commands.md

Common patterns for running commands with default or custom token configurations.

```bash
# Default: sets GITHUB_TOKEN
ghtkn exec -- gh pr view

# Custom environment variable
ghtkn exec -e GH_TOKEN -- gh pr view

# Specific app
ghtkn exec -e GH_TOKEN:my-org/read -- gh pr view

# Multiple apps
ghtkn exec \
  -e READ_TOKEN:my-org/read \
  -e WRITE_TOKEN:my-org/write \
  -- bash multi-app-script.sh
```

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

### Start the agent server

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/_autodocs/api-reference/agent-server.md

Runs the server in the foreground, listening on a Unix domain socket until the context is canceled.

```go
ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer cancel()

logger := slog.Default()
server := server.New("1.0.0")
if err := server.Start(ctx, logger); err != nil {
	log.Fatalf("Agent failed: %v", err)
}
```

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

### Verify installed tool version

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/docs/go-sdk.md

Check the version of the installed binary to compare against the latest release.

```bash
<tool> --version
```

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

### Example ghtkn configuration file

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

The YAML configuration file structure for defining GitHub Apps.

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

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

### Start Agent Server

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/_autodocs/cli-commands.md

Runs the agent server in the foreground, listening on a Unix socket.

```bash
ghtkn agent start [--config CONFIG]
```

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

### Configure ghtkn via YAML

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

Example configuration file defining application settings, backend storage type, and clipboard integration.

```yaml
apps:
  - name: my-org/app
    client_id: Iv1.abc123...

backend:
  type: keyring  # or "agent", "text"

clipboard:
  enable: true
```

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

### Command Signature

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/_autodocs/cli-commands.md

The basic syntax for executing the get command.

```bash
ghtkn get [--format FORMAT] [--min-expiration DURATION] [--config CONFIG]
```

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

### Verify assets with slsa-verifier

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

Install slsa-verifier via aqua and verify artifact provenance.

```sh
aqua g -i slsa-framework/slsa-verifier
```

```sh
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"
```

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

### Example of mutually exclusive app configuration

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/docs/git-credential-helper.md

Demonstrates assigning an owner to only one app to avoid conflicts.

```yaml
apps:
  - name: suzuki-shunsuke/write
    client_id: xxx
    git_owner: suzuki-shunsuke # Using this app if the repository owner is suzuki-shunsuke
  - name: suzuki-shunsuke/read-only
    client_id: xxx
    # git_owner: suzuki-shunsuke # Don't set `git_owner` to read-only app to push commits
```

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

### Verify assets with Cosign

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

Install Cosign via aqua and verify blob signatures and checksums.

```sh
aqua g -i sigstore/cosign
```

```sh
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 -
```

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

### Container entrypoint script

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/docs/agent-deployment.md

A wrapper script to start the agent in the background before executing the main container process.

```bash
#!/usr/bin/env bash
# entrypoint.sh
set -eu
ghtkn agent start &
exec "$@"
```

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

### Define Top-Level Configuration Structure

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

Example of the full YAML configuration structure including apps, backend, clipboard, and device flow settings.

```yaml
apps:
  - name: suzuki-shunsuke/app-name
    client_id: Iv1.abc123def456...
    
  - name: my-org/read-only
    client_id: Iv1.xyz789...

backend:
  type: keyring  # or "agent", "text"
  
clipboard:
  enable: false

device_flow:
  open_browser: true
```

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

### ghtkn auth command usage

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

Displays help information and usage examples for the authentication command.

```console
$ ghtkn auth --help
Authenticate to GitHub and cache an access token without printing it.

Unlike 'ghtkn get', this regenerates the token regardless of any cached token, so
running it proactively refreshes the cached token before it expires. Regeneration
normally runs the OAuth device flow; with the agent backend and refresh enabled, a
valid stored refresh token is used to refresh silently and the device flow runs
only when no usable refresh token exists. This is the only command that runs the
device flow, so it is only ever started by you, never on your behalf by 'ghtkn get',
'ghtkn exec', the Git credential helper, or a tool built on the ghtkn SDK. Run it in
your own interactive terminal: it waits for you to enter a one-time code.
It does not accept --min-expiration. Use --clipboard to copy the one-time code to the
clipboard. If an app name is omitted, GHTKN_APP or the default app is used.

$ ghtkn auth
$ ghtkn auth my-app
$ ghtkn auth -p

Usage:
  ghtkn auth [<app-name>] [flags]

Flags:
  -p, --clipboard   Copy the device flow one-time code to the clipboard
  -h, --help        help for auth

Global Flags:
  -c, --config string      configuration file path [$GHTKN_CONFIG]
      --log-level string   Log level (debug, info, warn, error) [$GHTKN_LOG_LEVEL]
```

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

### Start

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/_autodocs/api-reference/agent-server.md

Runs the agent server in the foreground, opening a Unix domain socket to serve clients until the context is canceled or a STOP command is received.

```APIDOC
## func (s *Server) Start(ctx context.Context, logger *slog.Logger) error

### Description
Runs the agent server in the foreground. It opens the Unix domain socket and serves clients until the context is canceled or a STOP command is received, then removes the socket and exits.

### Parameters
- **ctx** (context.Context) - Yes - Context canceled by SIGINT or SIGTERM signal handler
- **logger** (*slog.Logger) - Yes - Structured logger for server events

### Returns
- **error** - nil on successful shutdown, or an error if startup or serving fails

### Example
```go
ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer cancel()

logger := slog.Default()
server := server.New("1.0.0")
if err := server.Start(ctx, logger); err != nil {
	log.Fatalf("Agent failed: %v", err)
}
```
```

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

### Verify assets with GitHub CLI

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

Install GitHub CLI via aqua and verify release attestations.

```sh
aqua g -i cli/cli
```

```sh
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
```

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

### Start and unlock the ghtkn agent

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/docs/refresh-token.md

Commands to start the agent and unlock it with refresh token support enabled.

```sh
ghtkn agent start
```

```sh
ghtkn agent unlock --enable-refresh
```

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

### Example Error Output in Containers

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

Typical error message encountered when the default OS keyring backend fails in containerized environments.

```console
$ ghtkn get
... ERR ghtkn failed error="get or create access token: get or create token: get a token from the backend: get a secret from the keyring: exec: \"dbus-launch\": executable file not found in $PATH"
```

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

### NewInput

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/_autodocs/api-reference/controller-auth.md

Creates a new Input instance with default production values, including SDK client setup.

```APIDOC
## func NewInput() (*Input, error)

### Description
Creates a new Input instance with default production values. Sets up the ghtkn SDK client and injects the clipboard implementation for one-time code copying.

### Returns
- *Input, error - New Input with production dependencies, or an error if client creation fails
```

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

### List stored client IDs

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/_autodocs/api-reference/tokenstore.md

Example usage of ClientIDs to iterate over and log all stored token identifiers.

```go
ids, err := store.ClientIDs()
if err != nil {
	return fmt.Errorf("list stored tokens: %w", err)
}
for _, id := range ids {
	log.Printf("Stored token for %s", id)
}
```

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

### Scrub store memory

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/_autodocs/api-reference/tokenstore.md

Example usage of Zero to clear the data key before discarding the store.

```go
store.Zero() // Before discarding store on lock
// A decrypt attempted after Zero fails with ErrDecryptToken
```

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

### Count stored tokens

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/_autodocs/api-reference/tokenstore.md

Example usage of Len to retrieve and log the number of stored tokens.

```go
count := store.Len()
log.Printf("Currently storing %d tokens", count)
```

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

### Get Command Syntax

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

Syntax for retrieving tokens with optional formatting and expiration constraints.

```bash
ghtkn get [--format json] [-m DURATION] [--config CONFIG]
```

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

### Usage Examples

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/_autodocs/cli-commands.md

Common usage patterns for retrieving tokens, including formatting, expiration requirements, and integration with the gh CLI.

```bash
# Get token in plain text
ghtkn get

# Get token as JSON
ghtkn get --format json

# Get token requiring 30+ more minutes validity
ghtkn get --min-expiration 30m

# Use specific app
GH_APP=my-org/read ghtkn get

# Get token and use in gh CLI
export GH_TOKEN=$(ghtkn get)
gh pr view
```

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

### Access ghtkn documentation via CLI

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

Use these commands to retrieve and read documentation directly from the installed ghtkn tool.

```bash
ghtkn docs list
```

```bash
ghtkn docs show <name>
```

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

### Manage Agent Lifecycle

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

Commands for starting, unlocking, checking status, stopping, and locking the GHTKN agent.

```sh
: Start the agent in the background
ghtkn agent start &
```

```sh
: Enter the passphrase
ghtkn agent unlock
```

```sh
: Check the agent status
ghtkn agent status
: Stop the agent
ghtkn agent stop
: Discard the in-memory data key without stopping the agent
ghtkn agent lock
```

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

### Handle Get Controller Errors

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

Demonstrates checking for context cancellation and logging fatal errors during token retrieval.

```go
if err := controller.Run(ctx, logger, input); err != nil {
    if errors.Is(err, context.Canceled) {
        log.Println("Operation canceled by user")
        os.Exit(130)
    }
    log.Fatalf("Failed to get token: %v", err)
}
```

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

### Initialize Controller

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/_autodocs/api-reference/controller-revoke.md

Create a new controller instance using the required dependencies.

```go
func New(input *Input) *Controller
```

```go
input := &revoke.Input{
	Client:  ghtknClient,
	Revoker: revokeLib,
}
controller := revoke.New(input)
```

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

### Initialize Input

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/_autodocs/api-reference/controller-get.md

Creates an Input instance with default production dependencies.

```go
func NewInput() (*Input, error)
```

```go
input, err := get.NewInput()
if err != nil {
	return fmt.Errorf("create controller input: %w", err)
}
```

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

### Example of failed agent connection

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/docs/sandbox-claude-code.md

Shows the error message encountered when the sandbox lacks permission to access the agent socket.

```console
$ ghtkn agent status
ERR ghtkn failed error="query the agent status: connect to the ghtkn agent: dial unix /Users/foo/.cache/ghtkn/agent.sock: connect: operation not permitted"
```

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

### JSON Output Format

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/_autodocs/cli-commands.md

Example of the structured JSON output returned when the --format json flag is used.

```json
{
  "access_token": "ghu_16C7e42F292c6912E7710c838347Ae178B4a",
  "expiration_date": "2026-08-24T20:00:00Z"
}
```

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

### Initialize Configuration

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/_autodocs/cli-commands.md

Creates a default configuration file at the specified or default path.

```bash
ghtkn init [--config CONFIG]
```

```bash
# Create default config
ghtkn init

# Use custom path
ghtkn init -c /etc/ghtkn/config.yaml
```

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

### Initialize Controller Input

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/_autodocs/api-reference/controller-exec.md

Creates an Input instance with default production dependencies.

```go
func NewInput() (*Input, error)
```

```go
input, err := exec.NewInput()
if err != nil {
	return fmt.Errorf("create controller input: %w", err)
}
```

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

### Define Get Controller Input

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

The Input struct configures the token retrieval process, including output formatting and client interface requirements.

```go
type Input struct {
	OutputFormat    string    // "json" or empty
	Stdout          io.Writer
	IsGitCredential bool
	Client          Client
}
```

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

### Initialize Controller

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/_autodocs/api-reference/controller-auth.md

Creates a new Controller instance using the provided input configuration.

```go
func New(input *Input) *Controller
```

```go
input := &auth.Input{
	Client: client,
}
controller := auth.New(input)
```

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

### Run(logger, env, name, args...) (int, error)

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/_autodocs/api-reference/process-runner.md

Executes an external command with the specified environment and arguments, returning the exit code or an error if the command fails to start.

```APIDOC
## Run(logger, env, name, args...) (int, error)

### Description
Runs the specified command. On Unix-like systems, this replaces the current process via execve(2). On Windows, it runs as a child process and returns upon completion.

### Parameters
- **logger** (*slog.Logger) - Required - Structured logger for errors
- **env** ([]string) - Required - Environment variables (format: "KEY=value")
- **name** (string) - Required - Command name or absolute path
- **args** (...string) - Optional - Command arguments

### Returns
- **int** - Exit code (0 on success, non-zero on failure)
- **error** - Error if the command could not be started

### Errors
- **127** - Command not found
- **126** - Command cannot be executed (permissions)
- **exitCodeUnclassified** - Execution failed for another reason
```

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

### Initialize Token Store

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/_autodocs/api-reference/tokenstore.md

Create a new instance of the token store with a 32-byte data key and a storage directory.

```go
func New(dataKey []byte, dir string) *Store
```

```go
dataKey := make([]byte, 32) // 256-bit key from keyfile
dir := "/home/user/.cache/ghtkn/tokens"
store := tokenstore.New(dataKey, dir)
```

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

### Create Controller Input

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/_autodocs/api-reference/controller-revoke.md

Generate input with default production dependencies.

```go
func NewInput() (*Input, error)
```

```go
input, err := revoke.NewInput()
if err != nil {
	return fmt.Errorf("create controller input: %w", err)
}
```

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

### Retrieve user access token

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

Outputs a user access token starting with ghu_.

```sh
ghtkn get
```

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

### New

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/_autodocs/api-reference/controller-revoke.md

Creates a new Controller instance with the provided input dependencies.

```APIDOC
## func New(input *Input) *Controller

### Description
Creates a new Controller with the provided input.

### Parameters
- **input** (*Input) - Required - The controller input with dependencies

### Returns
- *Controller - A new controller instance
```

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

### Initialize a new agent server

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/_autodocs/api-reference/agent-server.md

Creates a server instance in a locked state, requiring an unlock command later.

```go
version := "1.0.0" // or os.Getenv("VERSION")
server := server.New(version)
```

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

### New

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/_autodocs/api-reference/controller-auth.md

Creates a new Controller instance with the provided input configuration.

```APIDOC
## func New(input *Input) *Controller

### Description
Creates a new Controller instance with the provided input configuration.

### Parameters
- **input** (*Input) - Required - The controller input with all dependencies

### Returns
- *Controller - A new controller instance
```

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

### Refresh token removal prompt

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/docs/refresh-token.md

Example of the confirmation prompt when unlocking without the --enable-refresh flag.

```console
$ ghtkn agent unlock
Enter the agent passphrase:
Stored refresh tokens will be dropped (access tokens are kept; affected apps re-authenticate on next expiry). Rerun with --enable-refresh to keep them. Continue? (y/N):
```

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

### Display ghtkn version help

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

View the usage instructions and available flags for the version command.

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

Usage:
  ghtkn version [flags]

Flags:
  -h, --help   help for version
  -j, --json   Output version in JSON format

Global Flags:
  -c, --config string      configuration file path [$GHTKN_CONFIG]
      --log-level string   Log level (debug, info, warn, error) [$GHTKN_LOG_LEVEL]
```

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

### Initialize Runner instance

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/_autodocs/api-reference/process-runner.md

Create a new runner using standard system streams.

```go
runner := proc.New(os.Stdin, os.Stdout, os.Stderr)
```

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

### Configure Backend via Configuration File

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

Specify the backend type in the .backend.type configuration file.

```yaml
backend:
  type: agent # text, keyring
```

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

### Start and Unlock ghtkn Agent

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/docs/sandbox-codex.md

Commands to initialize and unlock the ghtkn agent outside of the sandbox environment.

```sh
ghtkn agent start
ghtkn agent unlock
```

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

### New

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/_autodocs/api-reference/agent-server.md

Creates a new agent server instance. The server initializes in a locked state and requires an UNLOCK command to load the data key.

```APIDOC
## func New(version string) *Server

### Description
Creates a new agent Server. The server starts in a locked state (no token store); it is unlocked later via the UNLOCK command.

### Parameters
- **version** (string) - No - ghtkn version the agent reports in STATUS response (empty becomes UnknownVersion)

### Returns
- ***Server** - A new server instance in locked state

### Example
```go
version := "1.0.0"
server := server.New(version)
```
```

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

### Display ghtkn help information

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

View the main help menu and list of available subcommands.

```console
$ ghtkn --help
Create GitHub App User Access Tokens for secure local development.

ghtkn issues short-lived GitHub App User Access Tokens via the OAuth device flow
and caches them in a backend (OS keyring, the ghtkn agent, or a plain text file).
Use it to authenticate the gh CLI, Git, and other tools without long-lived
Personal Access Tokens.

See each subcommand's help with 'ghtkn help <command>'.
See https://github.com/suzuki-shunsuke/ghtkn for details.

If you are a coding agent, run 'ghtkn docs list' to list the documentation and
'ghtkn docs show <doc>' to read it before answering questions about ghtkn or
troubleshooting its errors.

Usage:
  ghtkn [flags]
  ghtkn [command]

Available Commands:
  agent          Manage the ghtkn agent that caches access tokens and serves them over a Unix socket
  auth           Authenticate to GitHub and cache an access token without outputting it
  completion     Generate the autocompletion script for the specified shell
  docs           Output document for coding agent
  exec           Run a command with access tokens in environment variables
  get            Output a GitHub App User Access Token to stdout
  git-credential Git Credential Helper
  help           Help about any command
  info           Output information about the environment which is useful for troubleshooting
  init           Create ghtkn.yaml if it doesn't exist
  json-schema    Output JSON Schema for the configuration file
  revoke         Revoke GitHub App User Access Tokens
  version        Show version

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

Use "ghtkn [command] --help" for more information about a command.
```

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

### Permission Denied Error

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

Indicates the command exists but lacks executable permissions.

```text
exec: permission denied
```

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

### Get

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/_autodocs/api-reference/tokenstore.md

Retrieves and decrypts a token for a given client ID. The token is decrypted on-demand and not cached in plaintext.

```APIDOC
## func (s *Store) Get(clientID string) (json.RawMessage, bool, error)

### Description
Returns the decrypted token for clientID. The bool result is false when no token is stored for the client ID.

### Parameters
- **clientID** (string) - Required - Client ID identifying the stored token

### Returns
- **json.RawMessage** - Decrypted token bytes
- **bool** - True if token found, false if not stored
- **error** - Error if read or decryption failed
```

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

### NewInput

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/_autodocs/api-reference/controller-revoke.md

Creates a new Input instance with default production dependencies.

```APIDOC
## func NewInput() (*Input, error)

### Description
Creates a new Input with default production dependencies.

### Returns
- *Input, error - New Input with production dependencies, or an error if client creation fails

### Errors
- **error** - Failed to create the ghtkn SDK client
```

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

### Initialize Clipboard Function

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/_autodocs/api-reference/clipboard.md

Returns a function that satisfies the SDK's deviceflow.CopyTextToClipboard signature.

```go
func New() func(ctx context.Context, text string) error
```

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

### Delete expired tokens with DeleteIf

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/_autodocs/api-reference/tokenstore.md

Example usage of DeleteIf to remove tokens based on an expiration date field.

```go
deleted, err := store.DeleteIf("Iv1.abc123def456", func(raw json.RawMessage) bool {
	token := &struct {
		ExpirationDate time.Time `json:"expiration_date"`
	}{}
	json.Unmarshal(raw, token)
	return time.Now().After(token.ExpirationDate)
})
if err != nil {
	return err
}
if deleted {
	log.Println("Expired token was deleted")
}
```

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

### Initialize ghtkn configuration

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

Generates the default configuration file for ghtkn.

```sh
ghtkn init
```

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

### ghtkn revoke command examples

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/_autodocs/cli-commands.md

Various ways to invoke the revoke command for raw tokens, app tokens, or all tokens.

```bash
# Revoke raw token directly
ghtkn revoke ghu_1234567890abcdef...

# Revoke app's cached token
ghtkn revoke -a my-org/app

# Revoke multiple apps
ghtkn revoke -a my-org/read -a my-org/write

# Revoke all apps' cached tokens
ghtkn revoke --all

# Revoke both raw tokens and app tokens
ghtkn revoke ghu_abc123 ghu_def456 -a my-org/app

# Revoke default app
ghtkn revoke
```

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

### Select GitHub App via Command Line

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/docs/multiple-apps.md

Specify the app name defined in the configuration file as a command-line argument.

```sh
ghtkn get suzuki-shunsuke/write
```

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

### Run

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/_autodocs/api-reference/controller-auth.md

Authenticates to GitHub and stores an access token in the backend, running the device flow when necessary.

```APIDOC
## func (c *Controller) Run(ctx context.Context, logger *slog.Logger, input *ghtkn.InputAuth) error

### Description
Authenticates to GitHub and stores an access token in the backend, running the device flow when it needs to. It always regenerates the token, so running it proactively refreshes the cached token before it expires.

### Parameters
- **ctx** (context.Context) - Required - Context for cancellation
- **logger** (*slog.Logger) - Required - Structured logger
- **input** (*ghtkn.InputAuth) - Required - Authentication configuration (see ghtkn-go-sdk)

### Returns
- error - nil on success, or an error describing the failure
```

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

### Configure ghtkn backend

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/docs/refresh-token.md

Set the backend to agent via environment variable or configuration file.

```sh
export GHTKN_BACKEND=agent
```

```yaml
# ~/.config/ghtkn/ghtkn.yaml
backend:
  type: agent
```

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

### Check ghtkn agent status

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/docs/agent-deployment.md

Example of the error message encountered when attempting to access the agent socket directly on macOS.

```console
$ ghtkn info
... error="query the agent status: connect to the ghtkn agent: dial unix /home/foo/.cache/ghtkn/agent.sock: connect: operation not supported"
```

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

### Restart the ghtkn agent

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

Stop the existing agent process before starting a new one to ensure the updated binary is used.

```sh
ghtkn agent stop
ghtkn agent start &
ghtkn agent unlock
```

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

### Execute command with custom environment

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/_autodocs/api-reference/process-runner.md

Run a command using a specific set of environment variables.

```go
runner := proc.New(os.Stdin, os.Stdout, os.Stderr)
env := []string{
	"PATH=/usr/local/bin:/usr/bin:/bin",
	"GH_TOKEN=ghu_abc123",
	"HOME=/home/user",
}
code, err := runner.Run(logger, env, "bash", "-c", "gh issue list")
if err != nil {
	fmt.Fprintf(os.Stderr, "Error: %v\n", err)
	os.Exit(code)
}
```

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

### Access documentation

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/_autodocs/cli-commands.md

Lists or displays specific documentation topics.

```bash
ghtkn docs list
ghtkn docs show <NAME>
```

```bash
ghtkn docs list
ghtkn docs show exec
ghtkn docs show configuration
```

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

### Handle Invalid Socket Path Error

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/docs/sandbox-codex.md

Example of the error message displayed when an invalid or relative path is provided for the network proxy.

```console
Error: failed to start managed network proxy: failed to build network proxy state: invalid network.allow_unix_sockets[0]
```

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

### View ghtkn completion help

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

Displays the general help menu for the completion command and lists supported shells.

```console
$ ghtkn completion --help
Generate the autocompletion script for ghtkn for the specified shell.
See each sub-command's help for details on how to use the generated script.

Usage:
  ghtkn completion [command]

Available Commands:
  bash        Generate the autocompletion script for bash
  fish        Generate the autocompletion script for fish
  powershell  Generate the autocompletion script for powershell
  zsh         Generate the autocompletion script for zsh

Flags:
  -h, --help   help for completion

Global Flags:
  -c, --config string      configuration file path [$GHTKN_CONFIG]
      --log-level string   Log level (debug, info, warn, error) [$GHTKN_LOG_LEVEL]

Use "ghtkn completion [command] --help" for more information about a command.
```

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

### Configure and Use Agent Backend

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

Set the environment variable to use the agent backend and retrieve tokens.

```sh
export GHTKN_BACKEND=agent
ghtkn get
```

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

### Client.Get

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

Retrieves an access token and application configuration.

```APIDOC
## Client.Get

### Description
Retrieves an access token and application configuration using the provided input.

### Signature
`Get(ctx context.Context, logger *slog.Logger, input *ghtkn.InputGet) (*ghtkn.AccessToken, *ghtkn.AppConfig, error)`
```

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

### handleGet Method Signature

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/_autodocs/api-reference/agent-server.md

Retrieves cached tokens or initiates device flow based on client ID and refresh configuration.

```go
func (s *Server) handleGet(ctx context.Context, req *agentapi.Request, enableRefreshToken bool) *agentapi.Response
```

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

### ghtkn get

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/_autodocs/cli-commands.md

Retrieve a cached GitHub App User Access Token. This command checks for a valid token and optionally refreshes it if the backend supports it.

```APIDOC
## ghtkn get

### Description
Retrieve a cached GitHub App User Access Token. Returns the token in plain text or JSON format.

### Signature
`ghtkn get [--format FORMAT] [--min-expiration DURATION] [--config CONFIG]`

### Flags
- **--format** (-f) (string) - Optional - Output format: empty for plain text, "json" for JSON. Environment: GHTKN_OUTPUT_FORMAT.
- **--min-expiration** (-m) (duration) - Optional - Minimum remaining token validity (e.g., "1h", "30m"). Environment: GHTKN_MIN_EXPIRATION.
- **--config** (-c) (string) - Optional - Configuration file path. Environment: GHTKN_CONFIG.
- **--log-level** (string) - Optional - Logging level. Environment: GHTKN_LOG_LEVEL.

### Behavior
- Returns cached token if valid for min-expiration.
- On agent backend with refresh enabled, silently refreshes expiring tokens.
- Fails if no token can be obtained without running device flow.

### Exit Codes
- **0**: Successfully retrieved and printed token.
- **1**: Token retrieval failed.

### Examples
```bash
# Get token in plain text
ghtkn get

# Get token as JSON
ghtkn get --format json

# Get token requiring 30+ more minutes validity
ghtkn get --min-expiration 30m
```
```

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

### Input configuration structure

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/_autodocs/api-reference/controller-get.md

Defines dependencies and output configuration for the Controller.

```go
type Input struct {
	OutputFormat    string    // Output format ("json" or empty for plain text)
	Stdout          io.Writer // Output writer
	IsGitCredential bool      // Whether to output in Git credential helper format
	Client          Client
}
```

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

### Run

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/_autodocs/api-reference/controller-get.md

Executes the main logic for retrieving a GitHub App access token.

```APIDOC
## func (c *Controller) Run(ctx context.Context, logger *slog.Logger, input *InputRun) error

### Description
Executes the main logic for retrieving a GitHub App access token. Reads configuration and the token cached in the backend, retrieves the authenticated user's login for Git Credential Helper if necessary, and outputs the result in the requested format.

### Parameters
- **ctx** (context.Context) - Required - Context for cancellation
- **logger** (*slog.Logger) - Required - Structured logger
- **input** (*InputRun) - Required - Runtime configuration with token retrieval parameters

### Returns
- **error** - nil on success, or an error describing the failure

### Errors
- **error** - Token retrieval from backend failed
- **error** - Output formatting failed
```

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

### New

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/_autodocs/api-reference/tokenstore.md

Creates a new token store instance that persists encrypted tokens in the specified directory using the provided data key.

```APIDOC
## func New(dataKey []byte, dir string) *Store

### Description
Creates a token store that persists encrypted tokens under dir, encrypting them with dataKey.

### Parameters
- **dataKey** ([]byte) - Required - AES-256 encryption key (exactly 32 bytes)
- **dir** (string) - Required - Directory for token storage (must exist)

### Returns
- *Store - A new store instance
```

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

### Configure Token Storage Backend

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

Set the storage backend for tokens. Options include 'keyring', 'agent', or 'text'.

```yaml
backend:
  type: agent
```

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

### Print resolved configuration

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/docs/go-sdk.md

Display the resolved configuration, active backend, and all relevant GHTKN environment variables.

```bash
ghtkn info
```

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

### Configure fish autocompletion

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

Provides instructions and help for setting up fish shell completion.

```console
$ ghtkn completion fish --help
Generate the autocompletion script for the fish shell.

To load completions in your current shell session:

	ghtkn completion fish | source

To load completions for every new session, execute once:

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

You will need to start a new shell for this setup to take effect.

Usage:
  ghtkn completion fish [flags]

Flags:
  -h, --help              help for fish
      --no-descriptions   disable completion descriptions

Global Flags:
  -c, --config string      configuration file path [$GHTKN_CONFIG]
      --log-level string   Log level (debug, info, warn, error) [$GHTKN_LOG_LEVEL]
```

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

### Configure App Switching with direnv

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/docs/multiple-apps.md

Use .envrc files to automatically set the GHTKN_APP environment variable based on the current directory.

```sh
source_up

export GHTKN_APP=suzuki-shunsuke/write
```

```sh
source_up

export GHTKN_APP=aquaproj/write
```

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

### Command Not Found Error

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

Indicates the command binary is missing or not in the system PATH.

```text
exec: command not found
```

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

### Configure Token Selection via Environment Variables

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

Set GHTKN_APP to specify a GitHub App or GHTKN_GITHUB_TOKEN to use a raw token directly, which takes precedence over app configuration.

```bash
export GHTKN_APP=suzuki-shunsuke/read-only
ghtkn get  # Uses specified app

export GHTKN_GITHUB_TOKEN=ghu_...
ghtkn get  # Uses raw token, ignores GHTKN_APP
```

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

### Verify Process Replacement on Unix

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

Demonstrates that ghtkn replaces its own process with the target command on Linux and macOS.

```console
$ ghtkn exec -- sleep 30 &
$ ps -o comm= -p $!
sleep
```

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

### Single App Usage

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

Common commands for interacting with a single configured app.

```bash
ghtkn auth              # Authenticate with the only app
ghtkn get               # Get token for the only app
ghtkn exec -- gh pr view  # Run command with token
```

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

### Multiple Apps Usage

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

Commands for authenticating and using specific apps or multiple apps simultaneously.

```bash
# Authenticate all apps
ghtkn auth -a my-org/read-only
ghtkn auth -a my-org/write-access
ghtkn auth -a other-org/api

# Use specific app
ghtkn exec -e GH_TOKEN:my-org/read-only -- gh pr list

# Use multiple apps in one command
ghtkn exec \
  -e GITHUB_TOKEN:my-org/read-only \
  -e WRITE_TOKEN:my-org/write-access \
  -- bash multi-app-script.sh
```

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

### Auth Command Syntax

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

Syntax for authenticating with GitHub Apps.

```bash
ghtkn auth [-a APP] [-p] [--config CONFIG]
```

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

### Execute gh command

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/_autodocs/api-reference/process-runner.md

Run an external command and handle potential startup errors.

```go
logger := slog.Default()
env := append(os.Environ(), "GH_TOKEN=ghu_...")
code, err := runner.Run(logger, env, "gh", "pr", "view")
if err != nil {
	// Command could not be started
	log.Printf("Failed to start command: %v (code: %d)", err, code)
	os.Exit(code)
}
// On Unix: this does not execute (process was replaced)
// On Windows: command finished with exit code in 'code'
```

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

### Define InputRun struct

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/_autodocs/api-reference/controller-exec.md

Configuration parameters for running a command.

```go
type InputRun struct {
	InputGet        *ghtkn.InputGet
	EnvVars         []*EnvVar
	Command         []string
	ContinueOnError bool
}
```

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

### Check version information

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/_autodocs/cli-commands.md

Displays version details, with an optional JSON output format.

```bash
ghtkn version [--json]
```

```text
ghtkn 1.0.0 (1a2b3c4d5e6f7g8h)
Go 1.26.6 linux/amd64
```

```json
{
  "version": "1.0.0",
  "sha": "1a2b3c4d5e6f7g8h",
  "go_version": "1.26.6"
}
```

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

### NewInput

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/_autodocs/api-reference/controller-get.md

Creates a new Input instance with default production values.

```APIDOC
## func NewInput() (*Input, error)

### Description
Creates a new Input instance with default production values. Sets up all necessary dependencies including file system, HTTP client, and keyring access.

### Returns
- *Input, error - New Input with production dependencies, or an error if client creation fails

### Errors
- **error** - Failed to create the ghtkn SDK client
```

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

### New(stdin, stdout, stderr *os.File) *Runner

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/_autodocs/api-reference/process-runner.md

Creates a new Runner instance configured with specific standard input, output, and error file descriptors.

```APIDOC
## New(stdin, stdout, stderr *os.File) *Runner

### Description
Creates a new Runner instance. The provided file descriptors are inherited by the executed command to maintain terminal control.

### Parameters
- **stdin** (*os.File) - Required - Standard input (typically os.Stdin)
- **stdout** (*os.File) - Required - Standard output (typically os.Stdout)
- **stderr** (*os.File) - Required - Standard error (typically os.Stderr)

### Returns
- ***Runner** - A new runner instance
```

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

### Dockerfile configuration for agent

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/docs/agent-deployment.md

Set the backend environment variable and define the entrypoint in your Dockerfile.

```dockerfile
ENV GHTKN_BACKEND=agent
ENTRYPOINT ["entrypoint.sh"]
```

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

### Configure Backend via Environment Variable

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

Set the GHTKN_BACKEND environment variable to change the storage backend to plaintext files.

```sh
export GHTKN_BACKEND=text
```

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

### Single App Configuration

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

YAML configuration for a single GitHub App using the keyring backend.

```yaml
apps:
  - name: suzuki-shunsuke/ghtkn
    client_id: Iv1.1234567890abcdef

backend:
  type: keyring

clipboard:
  enable: true
```

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

### Verify ghtkn and agent versions

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

Compare the binary version with the running agent version to determine if a restart is required.

```sh
ghtkn info | jq '{ghtkn: .version, agent: .agent.version}'
```

```json
{
  "ghtkn": "v0.3.4",
  "agent": "v0.3.1"
}
```

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

### Configure zsh autocompletion

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

Provides instructions and help for setting up zsh shell completion, including enabling compinit if necessary.

```console
$ ghtkn completion zsh --help
Generate the autocompletion script for the zsh shell.

If shell completion is not already enabled in your environment you will need
to enable it.  You can execute the following once:

	echo "autoload -U compinit; compinit" >> ~/.zshrc

To load completions in your current shell session:

	source <(ghtkn completion zsh)

To load completions for every new session, execute once:

#### Linux:

	ghtkn completion zsh > "${fpath[1]}/_ghtkn"

#### macOS:

	ghtkn completion zsh > $(brew --prefix)/share/zsh/site-functions/_ghtkn

You will need to start a new shell for this setup to take effect.

Usage:
  ghtkn completion zsh [flags]

Flags:
  -h, --help              help for zsh
      --no-descriptions   disable completion descriptions

Global Flags:
  -c, --config string      configuration file path [$GHTKN_CONFIG]
      --log-level string   Log level (debug, info, warn, error) [$GHTKN_LOG_LEVEL]
```

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

### View ghtkn docs help

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

Displays the help menu for the docs command, which is used to list or output documentation for coding agents.

```console
$ ghtkn docs --help
```

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

### Device Flow Integration

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/_autodocs/api-reference/clipboard.md

Injecting the clipboard capability into the ghtkn client during authentication.

```go
client, err := ghtkn.New()
if err != nil {
	return err
}

// Inject clipboard capability
client.SetCopyOnetimeCodeToClipboard(clipboard.New())

// When device flow runs, the code is automatically copied to clipboard
if err := client.Auth(ctx, logger, &ghtkn.InputAuth{...}); err != nil {
	return err
}
```

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

### List available documents

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

Lists all available document names and their descriptions.

```console
$ ghtkn docs list --help
```

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

### Configure systemd user service

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/docs/agent-deployment.md

Create this unit file in ~/.config/systemd/user/ghtkn-agent.service to manage the agent process.

```ini
[Unit]
Description=ghtkn agent

[Service]
ExecStart=/path/to/ghtkn agent start
Restart=on-failure

[Install]
WantedBy=default.target
```

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

### Generate shell completion script

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

Run this command to receive instructions for setting up shell completion for your specific shell.

```sh
ghtkn help completion
```

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

### Define Run function signature

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/_autodocs/api-reference/process-runner.md

The Run method executes a command with the provided environment and arguments.

```go
func (r *Runner) Run(logger *slog.Logger, env []string, name string, args ...string) (int, error)
```

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

### func NewInput() (*Input, error)

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/_autodocs/api-reference/controller-exec.md

Creates a new Input instance configured with default production dependencies.

```APIDOC
## func NewInput() (*Input, error)

### Description
Initializes a new Input object using default production dependencies. This is the standard way to prepare the controller for execution.

### Returns
- ***Input, error** - A new Input instance with production dependencies, or an error if the ghtkn SDK client creation fails.
```

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

### func New(input *Input) *Controller

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/_autodocs/api-reference/controller-exec.md

Creates a new Controller instance with the provided input dependencies.

```APIDOC
## func New(input *Input) *Controller

### Description
Creates a new Controller instance using the provided input configuration, which includes the client, runner, and environment variables.

### Parameters
- **input** (*Input) - Required - The controller input containing all necessary dependencies.

### Returns
- ***Controller** - A new controller instance.
```

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

### Retrieve system information

Source: https://github.com/suzuki-shunsuke/ghtkn/blob/main/_autodocs/cli-commands.md

Displays troubleshooting information in JSON format.

```bash
ghtkn info [--log-level LEVEL]
```

```json
{
  "ghtkn_version": "1.0.0",
  "go_version": "1.26.6",
  "os": "linux",
  "arch": "amd64",
  "config_path": "/home/user/.config/ghtkn/ghtkn.yaml",
  "backend": "keyring",
  "...": "..."
}
```
Tokens:
Raw