CLI Development

Patterns and best practices for building command-line interfaces using Commander.js, with focus on argument parsing, user experience, and output formatting.

When to use this skill

Use this skill when:

• Creating new CLI commands or subcommands

• Adding options, arguments, or flags to commands

• Parsing and validating user input

• Formatting CLI output (spinners, colors, tables)

• Handling errors and exit codes

• Writing help text and usage documentation

Commander.js Command Patterns

Basic Command Structure

import { Command } from 'commander'; import chalk from 'chalk'; import ora from 'ora';

export function createMyCommand(): Command { const command = new Command('mycommand');

command .description('Brief description of what this command does') .option('-f, --force', 'Force operation without confirmation') .option('-o, --output <path>', 'Output file path') .action(handleMyCommand);

return command; }

async function handleMyCommand(options: any): Promise<void> { const spinner = ora('Processing...').start();

try { // Command logic here spinner.succeed(chalk.green('✅ Operation completed')); } catch (error) { spinner.fail(chalk.red(❌ Failed: ${error instanceof Error ? error.message : String(error)})); process.exit(1); } }

Subcommands Pattern

From packages/liaison/src/commands/skill.ts :

export function createSkillCommand(): Command { const command = new Command('skill'); command.description('Manage Agent Skills');

// Subcommand: liaison skill init command .command('init') .description('Initialize Agent Skills in this project') .option('--global', 'Initialize globally (~/.skills/)') .option('--copy', 'Copy instead of symlink (Windows compatibility)') .option('--location <path>', 'Custom skills location') .action(initSkills);

// Subcommand: liaison skill create <name> command .command('create <name>') .description('Create a new skill') .option('--description <text>', 'Skill description') .option('--template <type>', 'Skill template (workflow, library, qa, deployment)', 'workflow') .option('--location <path>', 'Create skill at custom location') .action(createSkill);

return command; }

Argument and Option Patterns

Required Arguments

command .command('create <name>') // Required argument .action((name: string, options: any) => { console.log(Creating: ${name}); });

Optional Arguments

command .command('validate [path]') // Optional argument (square brackets) .action((path?: string) => { const targetPath = path || '.skills'; });

Options with Values

command .option('-o, --output <path>', 'Output file path') // Required value .option('-t, --template <type>', 'Template type', 'workflow') // With default .option('--format [fmt]', 'Output format', 'table') // Optional value

Boolean Flags

command .option('-f, --force', 'Force operation') .option('--no-cache', 'Disable caching') // Boolean negation

Input Validation

Validate Arguments

async function createSkill(name: string, options: any): Promise<void> { const spinner = ora('Creating skill...').start();

// Validate skill name format if (!name.match(/^[a-z0-9]+(-[a-z0-9]+)*$/)) { spinner.fail(chalk.red('Invalid skill name. Use lowercase alphanumeric with hyphens only.')); process.exit(1); }

// Check if already exists try { await fs.access(skillPath); spinner.fail(chalk.red(Skill "${name}" already exists at ${skillPath})); process.exit(1); } catch { // Good, doesn't exist yet }

// Proceed with creation... }

Validate Options

async function listSkills(options: any): Promise<void> { const validFormats = ['table', 'json', 'xml'];

if (options.format && !validFormats.includes(options.format)) { console.error(chalk.red(Invalid format: ${options.format})); console.error(chalk.yellow(Valid formats: ${validFormats.join(', ')})); process.exit(1); }

// Proceed... }

Output Formatting

Using Spinners (ora)

import ora from 'ora';

const spinner = ora('Loading...').start();

// Update spinner text spinner.text = 'Processing items...';

// Success spinner.succeed(chalk.green('✅ Operation completed'));

// Warning spinner.warn(chalk.yellow('⚠️ Warning message'));

// Failure spinner.fail(chalk.red('❌ Operation failed'));

// Stop without status spinner.stop();

Using Colors (chalk)

import chalk from 'chalk';

console.log(chalk.green('Success message')); console.log(chalk.yellow('Warning message')); console.log(chalk.red('Error message')); console.log(chalk.blue('Info message')); console.log(chalk.cyan('Highlight text')); console.log(chalk.bold('Bold text'));

Table Output

From packages/liaison/src/commands/skill.ts:252-260 :

// Format list as table console.log(chalk.bold('\nAvailable Skills:\n')); const table = skills .map(skill => ${chalk.cyan(skill.name.padEnd(30))} ${skill.description.substring(0, 60)} ) .join('\n'); console.log(table); console.log(\n Total: ${chalk.green(skills.length)} skill(s)\n);

JSON Output

if (options.format === 'json') { console.log(JSON.stringify(result, null, 2)); return; }

Error Handling

Graceful Error Messages

try { await performOperation(); } catch (error) { console.error(chalk.red(\n❌ Operation failed:\n)); console.error(chalk.red( ${error instanceof Error ? error.message : String(error)}));

if (options.verbose && error instanceof Error && error.stack) { console.error(chalk.dim('\nStack trace:')); console.error(chalk.dim(error.stack)); }

process.exit(1); }

Exit Codes

// Success process.exit(0);

// General error process.exit(1);

// Invalid usage process.exit(2);

// Validation error process.exit(3);

Help Text and Documentation

Command Description

command .description('Create a new skill') // Brief one-liner .usage('[options] <name>') // Usage pattern .addHelpText('after', Examples: $ liaison skill create my-skill $ liaison skill create my-skill --template library $ liaison skill create my-skill --description "My custom skill" );

Custom Help

command.addHelpCommand(false); // Disable default help command

command.on('--help', () => { console.log(''); console.log('Additional Information:'); console.log(' This command creates a new skill following the Agent Skills standard'); console.log(' Learn more: https://agentskills.io'); });

Common Patterns

Confirmation Prompts

import readline from 'readline';

async function confirmAction(message: string): Promise<boolean> { const rl = readline.createInterface({ input: process.stdin, output: process.stdout });

return new Promise(resolve => { rl.question(${message} (y/N): , answer => { rl.close(); resolve(answer.toLowerCase() === 'y'); }); }); }

// Usage if (!options.force && await confirmAction('Delete all data?')) { await deleteData(); }

Progress Indicators

for (let i = 0; i < items.length; i++) { spinner.text = Processing item ${i + 1} of ${items.length}...; await processItem(items[i]); }

Verbose Mode

function log(message: string, verbose: boolean = false): void { if (verbose) { console.log(chalk.dim([DEBUG] ${message})); } }

// Usage command.option('-v, --verbose', 'Enable verbose output');

async function myAction(options: any): Promise<void> { log('Starting operation...', options.verbose); // ... }

Verification

After implementing CLI features:

• Help text is clear and shows examples

• All options have descriptions

• Input validation provides helpful error messages

• Output is formatted consistently (colors, spinners)

• Exit codes are appropriate (0 for success, non-zero for errors)

• Error messages are user-friendly (no raw stack traces)

• Commands work with --help flag

• Progress feedback for long operations

Examples from liaison-toolkit

Example 1: Skill Create Command

// packages/liaison/src/commands/skill.ts:168-226 async function createSkill(name: string, options: any): Promise<void> { const spinner = ora('Creating skill...').start();

try { // Validate skill name if (!name.match(/^[a-z0-9]+(-[a-z0-9]+)*$/)) { spinner.fail(chalk.red('Invalid skill name. Use lowercase alphanumeric with hyphens only.')); process.exit(1); }

const skillsDir = options.location || '.skills';
const skillPath = join(skillsDir, name);

// Check if skill already exists
try {
  await fs.access(skillPath);
  spinner.fail(chalk.red(`Skill "${name}" already exists at ${skillPath}`));
  process.exit(1);
} catch {
  // Good, doesn't exist yet
}

// Create skill directory
spinner.text = 'Creating skill directory...';
await fs.mkdir(skillPath, { recursive: true });

// Create subdirectories
await fs.mkdir(join(skillPath, 'references'), { recursive: true });
await fs.mkdir(join(skillPath, 'scripts'), { recursive: true });
await fs.mkdir(join(skillPath, 'assets'), { recursive: true });

// Generate and write SKILL.md
spinner.text = 'Creating SKILL.md...';
const skillContent = generateSkillTemplate(
  name,
  options.description || `Skill: ${name}`,
  options.template,
);
await fs.writeFile(join(skillPath, 'SKILL.md'), skillContent);

spinner.succeed(chalk.green(`✅ Skill "${name}" created successfully`));
console.log(chalk.blue('\n📝 Next steps:'));
console.log(`  1. Edit: ${chalk.cyan(`${skillPath}/SKILL.md`)}`);
console.log(`  2. Add references: ${chalk.cyan(`${skillPath}/references/`)}`);
console.log(`  3. Validate: ${chalk.cyan(`liaison skill validate ${skillPath}`)}`);

} catch (error) { spinner.fail( chalk.red( Failed to create skill: ${error instanceof Error ? error.message : String(error)}, ), ); process.exit(1); } }

Example 2: Skill List Command

// packages/liaison/src/commands/skill.ts:232-269 async function listSkills(options: any): Promise<void> { const spinner = ora('Discovering skills...').start();

try { const locations = options.location ? [options.location] : ['.skills']; const skills = await discoverSkills({ locations });

spinner.stop();

if (skills.length === 0) {
  console.log(chalk.yellow('No skills found. Run: liaison skill create <name>'));
  return;
}

if (options.format === 'json') {
  console.log(JSON.stringify(skills, null, 2));
} else if (options.format === 'xml') {
  console.log(generateAvailableSkillsXml(skills));
} else {
  // Table format
  console.log(chalk.bold('\nAvailable Skills:\n'));
  const table = skills
    .map(
      (skill) =>
        `  ${chalk.cyan(skill.name.padEnd(30))} ${skill.description.substring(0, 60)}`,
    )
    .join('\n');
  console.log(table);
  console.log(`\n  Total: ${chalk.green(skills.length)} skill(s)\n`);
}

} catch (error) { spinner.fail( chalk.red( Failed to list skills: ${error instanceof Error ? error.message : String(error)}, ), ); process.exit(1); } }

Related Resources

• Commander.js Documentation

• chalk (Terminal colors)

• ora (Spinners)

• Node.js readline

• CLI UX best practices: 12 Factor CLI Apps