adding-a-command · git:20260329.8cf93fd · 2026-03-29 · sha256 89bb0603fff868af
adding-a-command git:20260329.8cf93fdA
Immutable. This exact content never changes and is served at /api/v1/blob/89bb0603fff868af.
No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_n6q2k5jys4zmqoi6/89bb0603fff868af8235d687660173a00fd542987031add7711acd6b35c7cff3.json
Then /plugin install adding-a-command@markdownregistry-n6q2k5jys4zmqoi6 in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.
---
name: adding-a-command
description: Creates a new CLI command following the Commander.js pattern in src/commands/. Handles command registration in src/cli.ts, telemetry tracking via tracked() wrapper, and option parsing. Use when user says 'add command', 'new CLI command', 'create subcommand', or asks to add files to src/commands/. Do NOT use for modifying existing commands or refactoring command logic.
---
# Adding a Command
## Critical
- **Every command must be wrapped with `tracked()`** — this enables telemetry. Without it, the command will not report usage.
- **Commands are registered in `src/cli.ts`**, not auto-discovered. You must manually import and attach each command.
- **Use Commander.js patterns exactly** — `.option()` for flags, `.argument()` for positional args, `.action()` for the handler.
- **Always provide a `.description()`** — it appears in `caliber --help`.
## Instructions
1. **Create the command file** in `src/commands/{{command-name}}.ts`.
- Signature: `export async function {{commandName}}(options: OptionType, ...args: any[]) { ... }`
- Use async/await for all async operations (DB, LLM, file I/O).
- Import `tracked` from `src/lib/hooks.ts`: `import { tracked } from '../lib/hooks.js';`
- Verify the command exports the handler function before proceeding.
2. **Define the OptionType interface** (if needed).
- Place above the handler function in the same file.
- Example from `score.ts`: `interface ScoreOptions { json?: boolean; verbose?: boolean; }`
- Verify the interface matches all `.option()` calls in Step 3.
3. **Register in `src/cli.ts`**.
- Import: `import { {{commandName}} } from './commands/{{command-name}}.js';`
- Attach to program: `program.command('{{cmd-name}}').description('...').option('--flag', '...').action(tracked({{commandName}}));`
- Use `.option()` for optional flags, `.argument()` for required positional args.
- Verify the import path includes `.js` extension (ESM).
4. **Add tests** in `src/commands/__tests__/{{command-name}}.test.ts`.
- Use Vitest + `vi.mock()` for LLM, file I/O, and hooks.
- Test both success and error paths.
- Verify tests pass: `npm run test -- {{command-name}}.test.ts`.
5. **Validate telemetry**.
- Confirm `tracked()` wraps the action handler.
- Verify the command fires an event in PostHog.
## Examples
**User says:** "Add a 'debug' command that prints the fingerprint JSON."
**Actions taken:**
1. Create `src/commands/debug.ts`:
```typescript
import { tracked } from '../lib/hooks.js';
import { collectFingerprint } from '../fingerprint/index.js';
export async function debug(options: { verbose?: boolean }) {
const fp = await collectFingerprint();
console.log(JSON.stringify(fp, null, 2));
}
```
2. Register in `src/cli.ts`:
```typescript
import { debug } from './commands/debug.js';
program
.command('debug')
.description('Print fingerprint JSON')
.option('--verbose', 'Include timing info')
.action(tracked(debug));
```
3. Test in `src/commands/__tests__/debug.test.ts`:
```typescript
vi.mock('../fingerprint/index.js');
it('should print fingerprint', async () => {
const consoleSpy = vi.spyOn(console, 'log');
await debug({ verbose: false });
expect(consoleSpy).toHaveBeenCalled();
});
```
**Result:** Running `caliber debug` prints the fingerprint and logs a telemetry event.
## Common Issues
- **"tracked is not defined"** — Verify import: `import { tracked } from '../lib/hooks.js';` with `.js` extension.
- **"Command not found"** — Check `src/cli.ts` for the import and `.action(tracked(...))` attachment.
- **"options is undefined"** — Ensure the handler signature is `async function(options: Type, ...args: any[])` and the Commander action passes options as the first parameter.
- **"PostHog event not firing"** — Confirm `tracked()` wraps the action handler; without it, events won't emit.
- **ESM import errors** — Always include `.js` extensions in import paths (e.g., `../lib/hooks.js` not `../lib/hooks`).