Adding A Command

Adding a Command

Critical

• Export pattern: Command must export a named async function: export async function myCommand(options?: OptionType). Never use default exports.
• Registration in cli.ts: Every command must be imported and registered with .command() chain in src/cli.ts, wrapped with tracked() for telemetry.
• Error signaling: Use throw new Error('__exit__') to exit gracefully without printing the error message. Use chalk for user-facing messages.
• Options typing: Commands receiving options must define a TypeScript interface for those options. Pass options as a destructured object parameter.

Instructions

1. Create the command file at src/commands/{commandName}.ts with named async export.

   • Signature: export async function {commandName}Command(options?: { optionName?: optionType }) { ... }
   • Import only what you need (avoid kitchen-sink imports).
   • Return void (handle all output via console.log or chalk).
   • Verify the file follows the naming convention: camelCase function + "Command" suffix.

2. Handle errors consistently: Wrap error-prone operations in try/catch. Distinguish between user errors and system errors:

   • User error (bad input): console.error(chalk.red('message')); throw new Error('__exit__');
   • System error (missing dependency): throw new Error('Detailed error message'); — this will print and exit with code 1.
   • Parse-like errors: Use ora spinner with .fail() before throwing.
   • This step prevents double error printing in bin.ts.

3. Import and register in src/cli.ts in the correct location:

   • Add import at the top: import { {commandName}Command } from './commands/{commandName}.js';
   • Register the command in the appropriate section (main commands, or nested under a group like sources).
   • For main commands: .command('{kebab-name}').description('...').option(...).action(tracked('{kebab-name}', {commandName}Command))
   • For subcommands (like sources add): sources.command('add').description(...).action(tracked('sources:add', sourcesAddCommand))
   • Key: Wrap handler with tracked('{command-name}', handler) for automatic telemetry.
   • Verify the command name in tracked() uses kebab-case for main commands and colon-separated for subcommands.

4. Define options (if needed):

   • Add .option() chains before .action(): .option('--flag', 'Description') or .option('--opt <value>', 'Description')
   • For parsed options (like comma-separated agents), add a parse function: .option('--opt <value>', 'Description', parseFunction)
   • Pass options to handler: .action(tracked('name', (opts) => command(opts)))
   • Define TypeScript interface for the options object.
   • Verify option names use camelCase (Commander converts kebab-case flags to camelCase).

5. Verify before proceeding:

   • Function exports correctly and is imported in cli.ts.
   • Command is registered with tracked() wrapper.
   • Output uses chalk for colors, not plain console.log.
   • Error paths throw new Error('__exit__') for user errors.

Examples

Example 1: Simple command (status)

User says: "Add a command to show config status"

Actions taken:

1. Create src/commands/status.ts with statusCommand() export
2. Import and register in src/cli.ts with tracked() wrapper

Result: caliber status displays config status; caliber status --json outputs JSON.

Code example:

import chalk from 'chalk';
import { loadConfig } from '../llm/config.js';

export async function statusCommand(options?: { json?: boolean }) {
  const config = loadConfig();
  
  if (options?.json) {
    console.log(JSON.stringify({ configured: !!config }, null, 2));
    return;
  }
  
  console.log(chalk.bold('Status'));
  console.log(`  LLM: ${chalk.green(config?.provider || 'Not configured')}`);
}

Registration in src/cli.ts:

import { statusCommand } from './commands/status.js';
program
  .command('status')
  .description('Show config status')
  .option('--json', 'Output as JSON')
  .action(tracked('status', statusCommand));