command-patterns.md

Command Patterns - Quick Reference

The best way to learn: see working examples that are tested and stay current.

---

Working Examples

examples/website/.commando/ - Full working project

Files:

• website.ts - Real commands with options, spinners, task lists
• examples.ts - Various pattern examples
• simple.ts - Minimal examples with module metadata

These are actual tested code that stays in sync with the implementation.

---

Basic Structure

export const myCommand: CommandoCommand = {
  description: 'Command description',

  defineCommand: (cmd) => {
    cmd
      .argument('<arg>', 'Argument description')
      .option('--flag', 'Flag description');
  },

  execute: async (options, args, context) => {
    // options.flag - parsed options
    // args[0] - positional arguments
    // context.commando, context.config, context.state
  }
};

---

Common Patterns

Simple Command

export const version = {
  description: 'Show version',
  execute: async () => console.log('v2.0.0')
};

With Options

export const deploy: CommandoCommand = {
  description: 'Deploy to environment',

  defineCommand: (cmd) => {
    cmd
      .argument('<env>', 'Environment name')
      .option('-s, --skip-tests', 'Skip tests');
  },

  execute: async (options, args) => {
    const env = args[0];
    if (!options.skipTests) await runTests();
    await deploy(env);
  }
};

With Spinner

import ora from 'ora';

export const build: CommandoCommand = {
  description: 'Build project',

  execute: async () => {
    const spinner = ora('Building...').start();
    try {
      await doBuild();
      spinner.succeed('Built!');
    } catch (err) {
      spinner.fail('Failed');
      throw err;
    }
  }
};

See examples/website/.commando/website.ts for complete real-world examples.

---

Module Configuration

# .commando/config.yml
modules:
  - ./website
  - ./examples

Commands are auto-discovered from module exports. See features/auto-discovery.md.

---

Learn More

How Features Work

• Auto-Discovery - How commands are discovered from exports
• Commander Integration - How options/arguments work
• Module Metadata - Customize groups with __module__
• Subcommand Groups - Organize commands

Using Libraries

• chalk - Terminal colors
• ora - Spinners
• listr2 - Multi-step tasks
• boxen - Success boxes
• More... - Full library reference

Examples

• examples/website/ - Complete working project (tested!)