Eigene CLI-Tools mit Claude entwerfen

1. Warum CLI-Design mehr ist als Argumente parsen

Der technische Teil eines CLI-Tools, also das Einlesen von Flags und Argumenten, ist mit modernen Bibliotheken wie Cobra für Go oder Click für Python meist in wenigen Zeilen erledigt. Die eigentliche Schwierigkeit liegt woanders: darin, ein mentales Modell zu entwerfen, das sich für erfahrene Terminal-Nutzer sofort vertraut anfühlt, weil es denselben Mustern folgt wie git, docker oder kubectl, statt eigene, scheinbar naheliegende Abkürzungen zu erfinden, die am Ende doch wieder nachgeschlagen werden müssen.

Claude eignet sich gut als Sparringspartner in dieser Entwurfsphase, weil es die Konventionen zahlreicher etablierter CLI-Tools kennt und gezielt darauf hinweisen kann, wenn ein geplanter Befehlsname oder ein Flag von diesen Konventionen abweicht. Wichtig ist, diese Fragen zu stellen, bevor die Struktur öffentlich genutzt wird, denn ein einmal veröffentlichtes CLI-Interface lässt sich später nur unter erheblichem Aufwand und mit Bruch bestehender Skripte ändern.

2. Command-Struktur nach POSIX-Konventionen durchdenken lassen

POSIX-Konventionen legen unter anderem fest, dass kurze Flags mit einem einzelnen Bindestrich und einem Buchstaben beginnen, während lange, sprechende Flags mit doppeltem Bindestrich geschrieben werden, etwa -v als Kurzform für --verbose. Viele moderne Tools erweitern dieses Schema um Subcommands nach dem Muster tool verb noun, etwa docker container ls, was sich gut skalieren lässt, wenn ein Tool im Laufe der Zeit um weitere Funktionsbereiche wächst.

Claude lässt sich gezielt bitten, einen geplanten Funktionsumfang gegen diese Konventionen zu prüfen und Inkonsistenzen aufzuzeigen, etwa wenn ein Flag in einem Subcommand --output heißt und in einem anderen --format, obwohl beide dasselbe Konzept meinen. Solche kleinen Inkonsistenzen fallen im eigenen Entwurf leicht nicht auf, weil man den eigenen Wortschatz kennt, sind für neue Nutzer aber eine der häufigsten Frustrationsquellen bei der ersten Benutzung eines unbekannten Tools.

# Geplante Command-Struktur gegen etablierte Konventionen prüfen lassen
claude "Ich plane ein CLI-Tool 'shipctl' für Deployment-Automatisierung mit \
  den Subcommands: deploy, rollback, status, logs. Prüfe die geplanten \
  Flags gegen die Konventionen von kubectl und docker. Zeige alle \
  Inkonsistenzen bei Flag-Namen zwischen den Subcommands auf.

3. Subcommand-Bäume nach dem Cobra- und Click-Pattern entwerfen

Sowohl Cobra in Go als auch Click in Python setzen auf einen Baum aus verschachtelten Commands, bei dem jeder Knoten eigene Flags, eine eigene Hilfe und eigene Unterkommandos besitzen kann, während gemeinsame Flags wie --verbose oder --config auf der Wurzel definiert und an alle Unterkommandos vererbt werden. Dieses Muster verhindert, dass dieselbe Flag-Definition an mehreren Stellen im Code dupliziert werden muss, und sorgt gleichzeitig für konsistentes Verhalten über das gesamte Tool hinweg.

Claude kann aus einer informellen Beschreibung der gewünschten Funktionalität ein passendes Grundgerüst für einen solchen Command-Baum entwerfen, inklusive sinnvoller Gruppierung verwandter Unterkommandos und der Entscheidung, welche Flags auf Root-Ebene und welche nur auf einem spezifischen Unterkommando sinnvoll sind. Diese Entwurfsarbeit vorab spart später erhebliche Refactoring-Arbeit, wenn ein zunächst flach gedachtes Tool um weitere Funktionsbereiche wächst.

package cmd

import (
	"github.com/spf13/cobra"
)

var rootCmd = &cobra.Command{
	Use:   "shipctl",
	Short: "Deployment-Automatisierung für interne Services",
}

var deployCmd = &cobra.Command{
	Use:   "deploy [service]",
	Short: "Deployt einen Service in die angegebene Umgebung",
	Args:  cobra.ExactArgs(1),
	RunE:  runDeploy,
}

func init() {
	rootCmd.PersistentFlags().BoolP("verbose", "v", false, "Ausführliche Ausgabe")
	rootCmd.PersistentFlags().String("config", "", "Pfad zur Konfigurationsdatei")
	deployCmd.Flags().String("env", "staging", "Ziel-Umgebung")
	rootCmd.AddCommand(deployCmd)
}

4. Sinnvolle Flags und Kurzformen konsistent benennen

Kurzformen von Flags sind wertvoll für den täglichen Gebrauch, werden aber schnell zur Falle, wenn dasselbe Kürzel in verschiedenen Subcommands unterschiedliche Dinge bedeutet, etwa -f einmal für --force und an anderer Stelle für --file. Nutzer, die ein Tool über Monate hinweg verwenden, entwickeln motorisches Gedächtnis für bestimmte Kürzel, und ein inkonsistentes Kürzel führt dann zu Fehlbedienungen, die sich erst nach der Ausführung, manchmal mit destruktiven Folgen, bemerkbar machen.

Claude lässt sich gut nutzen, um eine vollständige Liste aller geplanten Flags über alle Subcommands hinweg zu erstellen und dabei systematisch nach doppelt vergebenen Kürzeln mit unterschiedlicher Bedeutung zu suchen. Zusätzlich lohnt sich die Frage, welche Flags gefährliche, potenziell destruktive Operationen auslösen und deshalb bewusst keine kurze, leicht versehentlich eintippbare Form erhalten sollten, etwa ein erzwungenes Löschen, das immer explizit ausgeschrieben werden muss.

5. Hilfreiche Fehlermeldungen und --help-Texte generieren lassen

Eine Fehlermeldung, die nur mitteilt, dass etwas fehlgeschlagen ist, ohne zu erklären, warum und was der Nutzer als Nächstes tun sollte, kostet in Summe erheblich mehr Support-Aufwand als eine anfangs etwas ausführlichere Formulierung. Claude lässt sich gezielt bitten, aus einer technischen Fehlerursache, etwa einer fehlgeschlagenen Authentifizierung gegen eine API, eine Meldung zu formulieren, die den Grund benennt und einen konkreten nächsten Schritt vorschlägt, statt nur den rohen Fehlercode auszugeben.

Auch --help-Texte profitieren stark von gezielter Überarbeitung: Statt nur Flags aufzulisten, sollten sie ein bis zwei realistische Anwendungsbeispiele enthalten, die zeigen, wie die häufigsten Aufgaben tatsächlich gelöst werden. Claude kann aus der reinen Flag-Definition heraus passende Beispielaufrufe ableiten und dabei gezielt jene Kombinationen hervorheben, die laut vorhandenen Support-Anfragen oder GitHub-Issues am häufigsten zu Verwirrung führen.

# Vorher: kryptische Fehlermeldung ohne Handlungsanweisung
Error: 401

# Nachher, von Claude formuliert:
Error: Authentifizierung fehlgeschlagen (HTTP 401).
  Ihr API-Token ist entweder abgelaufen oder ungültig.
  Führen Sie 'shipctl auth login' aus, um sich erneut anzumelden.
  Details: shipctl auth status

6. Exit-Codes und maschinenlesbare Ausgabe konsistent gestalten

Ein CLI-Tool wird selten ausschließlich interaktiv genutzt, sondern häufig auch in Skripten und CI-Pipelines eingebunden, wo der Exit-Code über Erfolg oder Misserfolg entscheidet. Eine konsistente Konvention, bei der 0 immer Erfolg bedeutet, verschiedene Nicht-Null-Codes aber unterschiedliche Fehlerklassen unterscheiden, etwa Konfigurationsfehler versus Netzwerkfehler, erlaubt es aufrufenden Skripten, gezielt auf verschiedene Fehlerarten zu reagieren, statt jeden Fehler pauschal gleich zu behandeln.

Zusätzlich lohnt sich ein durchgängiges --json-Flag, das dieselbe Information wie die menschenlesbare Ausgabe in strukturierter Form liefert, damit sich das Tool zuverlässig in andere Automatisierung einbinden lässt. Claude kann helfen, ein konsistentes JSON-Schema über alle Subcommands hinweg zu entwerfen, sodass etwa das Feld für einen Fehlertext in jedem Subcommand denselben Namen trägt, statt sich von Befehl zu Befehl zu unterscheiden.

# Konsistente Exit-Codes für Skript-Integration
# 0 = Erfolg, 1 = allgemeiner Fehler, 2 = Konfigurationsfehler, 3 = Netzwerkfehler
shipctl deploy myservice --env production --json | jq -r '.status'
echo "Exit-Code: $?"  # skriptbar auswertbar ohne Textparsing

7. Distribution: npm, Homebrew oder Binary-Releases abwägen

Die Wahl des Distributionskanals hängt stark von der Zielgruppe ab und lässt sich nicht pauschal beantworten. Ein Tool, das primär von Node.js-Entwicklern genutzt wird, profitiert von einer npm-Veröffentlichung, weil die Zielgruppe bereits mit npm install -g vertraut ist, während dieselbe Wahl für ein Tool, das plattformunabhängig auch von Nicht-Node-Entwicklern genutzt werden soll, eine unnötige Node.js-Laufzeitabhängigkeit erzwingt, die viele potenzielle Nutzer abschreckt.

Claude lässt sich gut nutzen, um die eigene Zielgruppe und den technischen Kontext zu beschreiben und daraus eine begründete Empfehlung abzuleiten, statt der Distributionskanal einfach dem persönlichen Lieblingswerkzeug folgt. Für breit gestreute Zielgruppen bewährt sich häufig eine Kombination aus statisch kompilierten Binary-Releases über GitHub Releases als Basis, ergänzt um Homebrew für macOS-Nutzer und optional ein npm-Paket als dünner Wrapper für Node.js-Entwickler, die den gewohnten Installationsweg bevorzugen.

8. Shell-Completion für bash, zsh und fish generieren lassen

Automatische Vervollständigung von Befehlen, Flags und teils sogar dynamischen Werten wie verfügbaren Umgebungsnamen gehört bei etablierten CLI-Tools inzwischen zum Standard und wird von erfahrenen Terminal-Nutzern stillschweigend erwartet. Sowohl Cobra als auch Click bringen eingebaute Mechanismen mit, um Completion-Skripte für die gängigen Shells automatisch aus der Command-Definition zu generieren, ohne dass diese von Hand gepflegt werden müssen.

Claude eignet sich gut, um zu prüfen, ob die generierten Completion-Skripte tatsächlich alle Subcommands und Flags korrekt abdecken, und um bei komplexeren Fällen, etwa der dynamischen Vervollständigung von Umgebungsnamen aus einer laufenden API-Abfrage, den passenden Callback-Code für die jeweilige Bibliothek zu entwerfen. Diese Detailarbeit wird oft erst nach dem ersten Release nachgezogen, verbessert die wahrgenommene Qualität eines Tools aber überproportional stark im Verhältnis zum Implementierungsaufwand.

# Cobra generiert Completion-Skripte direkt aus der Command-Definition
shipctl completion bash > /etc/bash_completion.d/shipctl
shipctl completion zsh > "${fpath[1]}/_shipctl"
shipctl completion fish > ~/.config/fish/completions/shipctl.fish

9. Distributionskanäle im Vergleich

Die folgende Tabelle stellt gängige Distributionskanäle nach Zielplattform und Aufwand gegenüber.

10. Zusammenfassung

11. FAQ: CLI-Tools mit Claude entwerfen: Das Wichtigste auf einen Blick