scaffold-cli-commandScaffold new Commander.js CLI cmd → opts, action handler, 3 output modes (human|quiet|JSON), opt ceremony variant. Cmd naming, opt design, shared ctx, err handling, integ tests. Use → add cmd to existing CLI, design new CLI, standardize cmd structure.
Independent GitHub snapshot · Automated classification · Original documentation governs
Add cmd → Commander.js CLI w/ consistent opts, 3 output modes, integ tests.
gather, audit, sync)cli/index.js)<name>|[names...])Verb communicates action. Group:
| Category | Verbs | Pattern |
|---|---|---|
| CRUD | install, uninstall, list, search | Operates on content |
| Lifecycle | init, sync, audit | Manages project state |
| Ceremony | gather, scatter, tend, campfire | Warm narrative output |
Conventions:
install-skill — opts specify what)<required>|[optional]|[variadic...]program
.command('gather <name>')
.description('Gather a team around the campfire')
→ Cmd name, desc, positional args defined.
If err: verb overlaps existing → compose (add opt to existing) or differentiate in desc.
Standard set + cmd-specific.
Standard (as needed):
.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')
Cmd-specific — only what needed:
.option('--ceremonial', 'Show each item arriving individually')
.option('--only <items>', 'Comma-separated subset to include')
.option('-y, --yes', 'Skip confirmation prompts')
Rules:
-n) for frequent--dry-run) for clarity→ Complete opt chain w/ standard + custom.
If err: too many opts (>8) → split into subcmds or group related.
Consistent pattern:
.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);
}
})
getContext() shared helper centralizes:
→ Handler follows 5-step: ctx → resolve → preview → exec → output.
If err: cmd doesn't fit resolve-then-exec (purely informational like detect) → simplify: ctx → compute → output.
Default (human):
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 — concise lines w/ status icons (+, -, =, !), no ceremony, no decoration.
JSON (--json):
{
"command": "install",
"items": 3,
"installed": 2,
"skipped": 1,
"failed": 0
}
Pattern:
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);
→ All 3 modes useful. JSON parseable. Quiet concise. Default informative.
If err: no meaningful JSON (detect) → skip + document why.
For cmds benefiting from warm narrative:
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,
});
}
Voice rules:
See design-cli-output skill for terminal patterns.
→ Ceremony follows voice rules → warm informative narratives.
If err: ceremony forced or doesn't add info → skip. Not every cmd needs.
// 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);
}
Err design:
process.exit(1) for unrecoverable--yes)→ All err paths helpful. Destructive needs confirm.
If err: confirm prompts break scripting → ensure --yes + --quiet bypass both.
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/);
});
});
See test-cli-application for comprehensive patterns.
→ ≥3 tests: dry-run, JSON, err. More for complex.
If err: execSync timeout → ↑timeout or check for interactive prompts blocking.
--help--dry-run, --quiet, --json) work--yes)--json.--yes for destructive + --quiet suppresses.process.exit(1) all errs. Tools check exit first.--scope etc → sensible defaults so users don't specify each time.--quiet = "min output for machines". Ceremony leak → scripts break.build-cli-plugin — build adapter/plugin cmds operate ontest-cli-application — comprehensive testing beyond Step 7design-cli-output — terminal design all verbosityinstall-almanac-content — well-structured CLI cmd example