scaffold-cli-commandScaffold a new CLI command using Commander.js with options, action handler, three output modes (human-readable, quiet, JSON), and optional ceremony variant. Covers command naming, option design, shared context patterns, error handling, and integration testing. Use when adding a command to an existing Commander.js CLI, designing a new CLI tool from scratch, …
Independent GitHub snapshot · Automated classification · Original documentation governs
Einen neuen Befehl zu einer Commander.js-CLI-Anwendung mit konsistenter Options-Behandlung, drei Ausgabe-Modi und Integrations-Tests hinzufuegen.
gather, audit, sync)cli/index.js)<name> oder [names...])Ein Verb auswaehlen das die Aktion des Befehls kommuniziert. Befehle in Kategorien gruppieren:
| Kategorie | Verben | Muster |
|---|---|---|
| CRUD | install, uninstall, list, search | Operiert auf Inhalt |
| Lifecycle | init, sync, audit | Verwaltet Projekt-State |
| Zeremonie | gather, scatter, tend, campfire | Warme narrative Ausgabe |
Namens-Konventionen:
install-skill — Optionen spezifizieren lassen was)<required> oder [optional] oder [variadic...]program
.command('gather <name>')
.description('Gather a team around the campfire')
Erwartet: Ein Befehlsname, eine Beschreibung und positionelle Args definiert.
Bei Fehler: Wenn das Verb mit einem existierenden Befehl ueberlappt, sie entweder komponieren (eine Option zum existierenden Befehl hinzufuegen) oder klar in der Beschreibung differenzieren.
Jeder Befehl sollte ein Standard-Set geteilter Optionen plus befehl-spezifische unterstuetzen.
Standard-Optionen (nach Bedarf einbeziehen):
.option('-n, --dry-run', 'Preview without making changes')
.option('-q, --quiet', 'Suppress human-readable output')
.option('--json', 'Output as JSON')
.option('-f, --framework <id>', 'Target specific framework')
.option('-g, --global', 'Use global scope')
.option('--scope <scope>', 'Scope: project, workspace, global', 'project')
.option('--source <path>', 'Path to tool root directory')
Befehl-spezifische Optionen — nur hinzufuegen was der Befehl braucht:
.option('--ceremonial', 'Show each item arriving individually')
.option('--only <items>', 'Comma-separated subset to include')
.option('-y, --yes', 'Skip confirmation prompts')
Design-Regeln:
-n) fuer haeufig genutzte Optionen--dry-run) fuer KlarheitErwartet: Eine vollstaendige Options-Kette mit beiden Standard- und Custom-Optionen.
Bei Fehler: Wenn zu viele Optionen akkumulieren (>8), in Erwaegung ziehen in Subbefehle aufzuteilen oder verwandte Optionen zu gruppieren.
Der Action-Handler folgt einem konsistenten Muster:
.action(async (name, options) => {
// 1. Get shared context (registries, adapters, paths)
const ctx = getContext(options);
// 2. Resolve what to operate on
const items = resolveItems(ctx, name, options);
if (!items || items.length === 0) {
reporter.error('Nothing found.');
process.exit(1);
}
// 3. Preview if dry-run
if (options.dryRun) reporter.printDryRun();
// 4. Execute the operation
const results = await executeOperation(items, ctx, options);
// 5. Output results (3 modes)
if (options.json) {
console.log(JSON.stringify(results, null, 2));
} else if (options.quiet) {
reporter.printResults(results);
} else {
printHumanOutput(results, options);
}
})
Der getContext()-Shared-Helper zentralisiert:
Erwartet: Ein Action-Handler der dem 5-Schritte-Muster folgt: Kontext → Aufloesen → Vorschau → Ausfuehren → Ausgabe.
Bei Fehler: Wenn der Befehl nicht in das Resolve-then-Execute-Muster passt (z.B. er ist rein informationell wie detect), vereinfachen zu: Kontext → Berechnen → Ausgabe.
Jeder Befehl sollte drei Ausgabe-Modi unterstuetzen:
Default (menschlich lesbar):
Installing 3 item(s) to Claude Code...
+ create-skill [claude-code] .claude/skills/create-skill
+ write-tests [claude-code] .claude/skills/write-tests
= commit-changes [claude-code] (skipped)
2 installed, 1 skipped
Quiet (--quiet):
Standard-Reporter-Ausgabe — praegnante Zeilen mit Status-Icons (+, -, =, !), keine Zeremonie, keine Dekoration.
JSON (--json):
{
"command": "install",
"items": 3,
"installed": 2,
"skipped": 1,
"failed": 0
}
Implementations-Muster:
if (options.json) {
console.log(JSON.stringify(data, null, 2));
return;
}
if (options.quiet) {
reporter.printResults(results);
return;
}
// Default: human-readable output
printHumanReadable(results, options);
Erwartet: Alle drei Modi produzieren nuetzliche Ausgabe. JSON ist parsebar. Quiet ist praegnant. Default ist informativ.
Bei Fehler: Wenn der Befehl keine bedeutungsvolle JSON-Repraesentation hat (z.B. detect), den JSON-Modus ueberspringen und dokumentieren warum.
Fuer Befehle die von warmer, narrativer Ausgabe statt transaktionalem Reporting profitieren:
if (options.json) {
ceremonyReporter.printJson(data);
} else if (options.quiet) {
reporter.printResults(results);
} else {
ceremonyReporter.printArrival({
teamId: name,
agents,
results: { installed, skipped, failed },
ceremonial: options.ceremonial || false,
});
}
Zeremonie-Ausgabe folgt Stimm-Regeln:
Siehe den design-cli-output-Skill fuer detaillierte Terminal-Ausgabe-Muster.
Erwartet: Zeremonie-Ausgabe die alle Stimm-Regeln befolgt und warme, informative Narrativen produziert.
Bei Fehler: Wenn die Zeremonie-Ausgabe sich erzwungen anfuehlt oder keine Information ueber die Standard-Ausgabe hinaus hinzufuegt, sie ueberspringen. Nicht jeder Befehl braucht eine Zeremonie-Variante.
// Unknown item
if (!item) {
reporter.error(`Unknown: ${name}. Use 'tool list' to browse.`);
process.exit(1);
}
// Confirmation for destructive actions
if (!options.yes && !options.quiet && !options.dryRun) {
const answer = await askYesNo('Proceed?');
if (!answer) {
console.log(' Cancelled.');
return;
}
}
// State validation
if (!state.fires[name]) {
reporter.error(`Not active. Nothing to remove.`);
process.exit(1);
}
Fehler-Design-Prinzipien:
process.exit(1) fuer nicht behebbare Fehler--yes)Erwartet: Alle Fehler-Pfade produzieren hilfreiche Nachrichten. Destruktive Operationen erfordern Bestaetigung.
Bei Fehler: Wenn Bestaetigungs-Prompts mit Skripting interferieren, sicherstellen dass --yes und --quiet beide sie umgehen.
import { describe, it, after } from 'node:test';
import assert from 'node:assert/strict';
import { execSync } from 'child_process';
const CLI = 'node cli/index.js';
function run(args) {
return execSync(`${CLI} ${args}`, { encoding: 'utf8', timeout: 10000 });
}
describe('new-command', () => {
after(() => { /* cleanup created files/state */ });
it('dry-run shows preview', () => {
const out = run('new-command arg --dry-run');
assert.match(out, /DRY RUN/);
});
it('--json outputs valid JSON', () => {
const out = run('new-command arg --json');
const start = out.indexOf('{');
const data = JSON.parse(out.slice(start));
assert.equal(data.command, 'new-command');
});
it('rejects unknown input', () => {
assert.throws(() => run('new-command nonexistent'), /Unknown/);
});
});
Siehe den test-cli-application-Skill fuer umfassende CLI-Test-Muster.
Erwartet: Mindestens 3 Tests: Dry-Run, JSON-Ausgabe, Fehler-Fall. Mehr fuer komplexe Befehle.
Bei Fehler: Wenn execSync Timeout erreicht, das Timeout erhoehen oder auf interaktive Prompts pruefen die den Befehl blockieren.
--help--dry-run, --quiet, --json) funktionieren korrekt--yes)--json implementieren auch wenn der Befehl interaktiv-only erscheint.--yes fuer destruktive Befehle bereitstellen und sicherstellen dass --quiet Prompts unterdrueckt.process.exit(1) fuer alle Fehler verwenden. Tools die CLI-Ausgabe parsen pruefen Exit-Codes zuerst.--scope sollten sinnvolle Defaults haben damit Benutzer sie nicht jedes Mal spezifizieren muessen.--quiet-Flag bedeutet "minimale Ausgabe fuer Maschinen". Wenn Zeremonie-Text in Quiet-Modus leckt, werden Skripte an unerwarteter Ausgabe brechen.build-cli-plugin — den Adapter/das Plugin bauen auf dem Befehle operierentest-cli-application — umfassende CLI-Test-Muster ueber die Basics in Schritt 7 hinausdesign-cli-output — Terminal-Ausgabe-Design fuer alle Verbosity-Stufeninstall-almanac-content — Beispiel eines gut strukturierten CLI-Befehls-Skills