adding-a-command · git:20260425.fa623ff · 2026-04-25 · sha256 82e1fc582c285999
adding-a-command git:20260425.fa623ffA
Immutable. This exact content never changes and is served at /api/v1/blob/82e1fc582c285999.
No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_6ump67rpsbapd5td/82e1fc582c285999aedb13837c03ede81096acdffa302952770313f263e64c30.json
Then /plugin install adding-a-command@markdownregistry-6ump67rpsbapd5td 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: Create a new CLI command following Commander.js pattern. Handles command file in src/commands/, 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 adds files to src/commands/. Do NOT use for modifying existing commands or refactoring command structure.
---
# Adding a Command
## Critical
- Commands MUST be registered in `src/cli.ts` using `.command()` and `.action()` with the `tracked()` wrapper for telemetry.
- Command file MUST be in `src/commands/{commandName}.ts` and export a default async function with signature: `async (options: CommandOptions, ctx: CLIContext) => Promise<void>`.
- Always use `tracked(commandName, async () => { ... })` wrapper in `src/cli.ts` to enable telemetry tracking.
- Test file MUST be in `src/commands/__tests__/{commandName}.test.ts` with at least one happy-path test.
## Instructions
1. **Create command file** in `src/commands/{commandName}.ts`
- Export default async function: `export default async (options: any, ctx: CLIContext) => { ... }`
- Import `CLIContext` from `src/cli.ts`
- Use `ctx.log()` for output (respects quiet mode via `--quiet`)
- Use `ctx.spinner()` for async operations
- Verify function signature matches existing commands like `src/commands/score.ts`
2. **Register in src/cli.ts**
- Import the command: `import addCommand from './commands/mycommand.js'`
- Add command definition:
```ts
program
.command('mycommand')
.description('One-line description')
.option('--option', 'Option description')
.action(tracked('mycommand', addCommand))
```
- Verify imports are `.js` (ESM)
- Verify `tracked()` wrapper is applied to `.action()`
3. **Add telemetry event** in `src/telemetry/events.ts`
- Add event type: `export type MyCommandEvent = { type: 'mycommand:start' | 'mycommand:success' | 'mycommand:error'; ... }`
- Include `duration?: number` field for timed events
- Update `export type AllEvents = ... | MyCommandEvent`
- Verify event matches pattern in existing events
4. **Create test file** in `src/commands/__tests__/{commandName}.test.ts`
- Import `describe`, `it`, `expect`, `vi` from `vitest`
- Import command from parent: `import addCommand from '../mycommand.js'`
- Create mock `CLIContext`: `{ log: vi.fn(), spinner: vi.fn().mockReturnValue({ start: vi.fn(), stop: vi.fn() }) }`
- Test happy path: `await addCommand({}, ctx); expect(ctx.log).toHaveBeenCalled()`
- Verify test runs: `npx vitest run src/commands/__tests__/{commandName}.test.ts`
5. **Build and validate**
- Run `npm run build` → verify no TypeScript errors
- Run `npm run lint` → verify ESLint passes
- Test command: `node dist/bin.js mycommand --help` → verify options listed
- Run `npm run test` → verify new test passes
## Examples
User says: "Add a new `verify` command that checks if config files exist"
**Actions:**
1. Create `src/commands/verify.ts`:
```ts
import { CLIContext } from '../cli.js';
export default async (options: any, ctx: CLIContext) => {
const spinner = ctx.spinner('Verifying config files...');
spinner.start();
const exists = await checkFilesExist();
spinner.stop();
ctx.log(`✓ Config files ${exists ? 'found' : 'missing'}`);
};
```
2. Register in `src/cli.ts`:
```ts
import verifyCommand from './commands/verify.js';
program
.command('verify')
.description('Verify configuration files exist')
.action(tracked('verify', verifyCommand))
```
3. Add to `src/telemetry/events.ts`:
```ts
export type VerifyEvent = {
type: 'verify:start' | 'verify:success' | 'verify:error';
duration?: number;
};
```
4. Create `src/commands/__tests__/verify.test.ts` with happy-path test
5. Run `npm run build && npm run test && npm run lint`
## Common Issues
**"Cannot find module './commands/mycommand.js'"**
- Verify file is at `src/commands/mycommand.ts` (TypeScript)
- Verify import in `src/cli.ts` uses `.js` extension: `from './commands/mycommand.js'`
- Rebuild: `npm run build`
**"tracked is not exported from src/cli.ts"**
- Verify `tracked()` function exists in `src/cli.ts` (it should; check existing commands)
- Verify you're using it as `.action(tracked('commandName', commandFunction))`
**Test fails with "CLIContext is not a constructor"**
- Create mock object manually: `const ctx = { log: vi.fn(), spinner: vi.fn().mockReturnValue({ start: vi.fn(), stop: vi.fn() }) }`
- Do NOT try to instantiate CLIContext; it's an interface
**"--option not recognized" when testing**
- Verify `.option()` is chained in `src/cli.ts` BEFORE `.action()`
- Rebuild and test with `npm run build && node dist/bin.js mycommand --help`