kmanage/README.md

kmanage

A fast, lightweight, and secure Go CLI tool for managing Komodo Core Stacks and Git Repositories / Webhooks with native Multi-Account support (Gitea, Forgejo, GitHub) and OS Keyring encryption (macOS Keychain, Windows Credential Manager, Linux SecretService).

---

Table of Contents

• Features
• Security Concept (OS Keyring)
• Installation & Build
• Configuration
  • 1. Configure Komodo
  • 2. Configure Git Accounts (Multi-Account)
  • 3. Manage Git Accounts
• Command Reference
  • Komodo (kmanage kmd)
  • Git Repositories (kmanage git)
  • Git Webhooks (kmanage git webhook)
  • PR Branch Auto-Deletion (kmanage git pr-autodel)
• Global Options
• Shell Auto-Completion
• Project Structure

---

Features

• 🔐 Zero Plaintext Secrets: Sensitive API keys and tokens are automatically stored encrypted in your operating system's native OS Keyring (Apple Keychain, Windows Credential Manager, Linux SecretService).
• 👥 Multi-Account & Multi-Provider: Manage multiple Git servers and accounts simultaneously (e.g. self-hosted Gitea + GitHub).
• 🚀 Komodo Core API Integration: Instant overview of stacks, servers, deploy status, linked Git providers, and webhook configurations.
• 🐙 Git Provider Integration (Gitea / Forgejo / GitHub):
  • List repositories with visibility, default branch, PR branch deletion status, and active webhooks.
  • Webhook Management: List webhooks by repo, delete by ID or URL, and run server-wide prune across one or all accounts.
  • PR Branch Auto-Clean: Enable or disable automatic branch deletion on PR merge (per repo, per owner/organization, or globally).
• ⚡ High Concurrency & Performance: Parallel API calls powered by goroutines with controlled worker pools.
• 📐 Dynamic Table Layout: Automatic column alignment via Go's tabwriter and full support for --no-header.
• 🔍 Dynamic Shell Auto-Completion: Instant <TAB> completion for commands, flags, accounts, owner names, and repository names (backed by a 3-minute local cache).

---

Security Concept (OS Keyring)

kmanage separates non-sensitive configuration metadata from sensitive credentials:

1. Non-Sensitive Metadata: Stored in ~/.kmanage.yaml (URLs, account names, default account).
2. Sensitive Secrets (komodo_key, komodo_secret, git_token): Stored in the encrypted OS Keyring.
3. Runtime Resolution Order:
   • 1. Direct environment variables (e.g. KMANAGE_KOMODO_KEY, KMANAGE_GIT_GITEA_TOKEN)
   • 2. Native OS Keyring (macOS Keychain / Windows Credential Manager / Linux SecretService)
   • 3. Local config file ~/.kmanage.yaml (fallback for headless servers/CI)

---

Installation & Build

Prerequisites

• Go 1.22+

Build

# Clone repository & compile binary
go build -o kmanage main.go

# Optional: move binary to PATH
sudo mv kmanage /usr/local/bin/

---

Configuration

1. Configure Komodo

kmanage kmd configure --url https://kmd.example.com --key <API_KEY> --secret <API_SECRET>

2. Configure Git Accounts (Multi-Account)

Add as many Git accounts as you need. The first added account is automatically set as the default.

# Add a Gitea / Forgejo account:
kmanage git configure --name gitea --url https://git.example.com --token <GITEA_ACCESS_TOKEN>

# Add a GitHub account:
kmanage git configure --name github --type github --token <GITHUB_PERSONAL_ACCESS_TOKEN>

# Add an additional work or organization account:
kmanage git configure --name work --url https://git.company.com --token <TOKEN>

3. Manage Git Accounts

# List all configured accounts:
kmanage git accounts

# Switch default account:
kmanage git set-default github

# Delete account (also removes token from OS keyring):
kmanage git delete-account work

Example ~/.kmanage.yaml

komodo_url: https://kmd.example.com
default_git_account: gitea
git_accounts:
    gitea:
        type: gitea
        url: https://git.example.com
    github:
        type: github
        url: https://api.github.com

(All tokens and secret keys are stored securely in the OS Keyring).

---

Command Reference

Komodo (kmanage kmd)

List Stacks

kmanage kmd list

Output:

NAME                SERVER   STATUS    PROVIDER       REPO                            WEBHOOK
----                ------   ------    --------       ----                            -------
authentik           DS920    running   git.hnrx.net   Docker/authentik                enabled
beszel              DS920    running   git.hnrx.net   Docker/beszel                   enabled
manage-servers      DS920    running   github.com     hnrx/manage-servers             enabled
...

---

Git Repositories (kmanage git)

List Repositories

# List repositories from default account:
kmanage git list repos

# List repositories from a specific account (-A / --account):
kmanage git list repos --account github

# List repositories across ALL configured accounts:
kmanage git list repos --all-accounts

Output:

ACCOUNT   REPOSITORY                     STATUS    BRANCH   PR AUTO-DEL   WEBHOOKS
-------   ----------                     ------    ------   -----------   --------
gitea     Docker/authentik               public    main     yes           https://kmd.example.com/... (active)
gitea     Docker/beszel                  public    main     yes           -
github    matthiashinrichs/docker-gitea  public    main     no            -
...

Initialize & Publish Current Directory as Git Repository (kmanage git init-repo)

Creates a remote repository for the current project directory, initializes local git if needed, stages all files, creates an initial commit ("Initial commit created by kmanage"), and pushes to main.

# Create repo with current directory name and push:
kmanage git init-repo

# Create repo with custom name under an organization / owner:
kmanage git init-repo my-service --org Docker

# Create a private repo on GitHub:
kmanage git init-repo --account github --private

# Custom commit message and initial branch:
kmanage git init-repo -b main -m "Initial commit created by kmanage"

---

Git Webhooks (kmanage git webhook)

Aliases: hook, hooks, webhooks

1. List Webhooks for a Repository

# In default account:
kmanage git webhook list Docker/authentik

# In a specific account:
kmanage git webhook list matthiashinrichs/docker-gitea --account github

2. Delete Webhooks from a Repository

# Delete single webhook by ID:
kmanage git webhook delete Docker/authentik --id 12

# Delete all webhooks in repository:
kmanage git webhook delete Docker/authentik --all

# Delete webhooks matching a target URL:
kmanage git webhook delete Docker/authentik --url kmd.example.com

# Skip confirmation prompt (CI / Scripting):
kmanage git webhook delete Docker/authentik --all -y

3. Webhook Prune (Search and batch delete across repositories)

# Dry-run preview:
kmanage git webhook prune --url kmd.example.com --dry-run

# Prune in default account:
kmanage git webhook prune --url kmd.example.com

# Prune across ALL configured Git accounts:
kmanage git webhook prune --url kmd.example.com --all-accounts -y

---

PR Branch Auto-Deletion (kmanage git pr-autodel)

Aliases: set-pr-autodel, autodel

Controls automatic deletion of head branches when pull requests are merged (compatible with Gitea default_delete_branch_after_merge and GitHub delete_branch_on_merge).

1. Single Repository

# Enable:
kmanage git pr-autodel enable Docker/authentik

# Disable on GitHub:
kmanage git pr-autodel disable matthiashinrichs/docker-gitea --account github

2. All Repositories of an Owner / Organization

# Enable for all repositories in organization 'Docker':
kmanage git pr-autodel enable --owner Docker

# Disable for all repositories in organization 'Docker':
kmanage git pr-autodel disable --owner Docker -y

3. Globally for ALL Accessible Repositories

kmanage git pr-autodel enable --all

---

Global Options

Flag	Description
--no-header	Omit table headers from output (ideal for scripting, awk, grep, or fzf).
-h, --help	Display help for the respective command.

Example with --no-header:

kmanage kmd list --no-header | awk '{print $1, $3}'

---

Shell Auto-Completion

kmanage provides dynamic shell auto-completion for commands, flags, account names, owner names, and repository names.

Zsh (macOS Default)

1. Test in current session:

   source <(kmanage completion zsh)
   

2. Persistent Setup:

   mkdir -p ~/.zsh/completion
   kmanage completion zsh > ~/.zsh/completion/_kmanage
   

   Add to your ~/.zshrc (before compinit):

   fpath=(~/.zsh/completion $fpath)
   autoload -Uz compinit && compinit
   

Bash

source <(kmanage completion bash)

Fish

kmanage completion fish | source

---

Project Structure

kmanage/
├── cmd/
│   ├── root.go                 # Root Cobra command & global flags (--no-header)
│   ├── kmd.go                  # Komodo parent command & kmd configure
│   ├── kmd_list.go             # kmanage kmd list
│   ├── git.go                  # Git parent command, accounts, configure & list
│   ├── git_webhook.go          # kmanage git webhook list/delete/prune
│   ├── git_pr_autodel.go       # kmanage git pr-autodel enable/disable
│   ├── helper_clients.go       # Multi-account client resolution & input helpers
│   ├── helper_config.go        # Secure config storage (~/.kmanage.yaml)
│   └── helper_completion.go    # Dynamic auto-completion & local TTL cache
├── pkg/
│   ├── secret/
│   │   └── secret.go           # Cross-platform OS Keyring abstraction
│   ├── komodo/
│   │   └── client.go           # Komodo Core API JSON-RPC client
│   └── git/
│       └── client.go           # Multi-provider REST client (Gitea / GitHub)
├── go.mod
├── go.sum
├── main.go                     # Application entrypoint
└── README.md                   # Documentation