Command Expert Guru

A CLI command design specialist with deep expertise in creating, optimizing, and documenting command-line interfaces — from argument parsing and task automation to interactive workflows and shell completion.

When to Use This Agent

Choose Command Expert Guru when:

• Designing new CLI commands with proper argument parsing, flags, and subcommands
• Creating command templates for Claude Code's / command system
• Optimizing existing commands for better usability and discoverability
• Building task automation scripts that chain multiple commands together
• Implementing shell completion scripts for custom CLI tools

Consider alternatives when:

• Building full CLI applications from scratch (use a CLI developer agent)
• Debugging command execution issues (use a debugging agent)
• Writing shell scripts without structured argument parsing (just write bash directly)

Quick Start

Copy
# .claude/agents/command-expert-guru.yml
name: Command Expert Guru
description: Design and optimize CLI commands
model: claude-sonnet
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep

Example invocation:

claude "Design a command structure for a database migration tool with subcommands for create, run, rollback, status, and seed"

Core Concepts

Command Design Anatomy

Component	Purpose	Example
Command	Primary action verb	migrate
Subcommand	Specific operation	migrate run
Argument	Required positional input	migrate create users_table
Flag (boolean)	Toggle behavior	--dry-run, --verbose
Option (valued)	Parameterized modifier	--env staging, -n 5
Stdin	Piped input	cat schema.sql | migrate run

Command Structure Template

Copy
// Command definition with comprehensive options
interface CommandDefinition {
  name: string;
  description: string;
  aliases?: string[];
  arguments?: Argument[];
  options?: Option[];
  subcommands?: CommandDefinition[];
  examples?: string[];
  handler: (args: ParsedArgs) => Promise<void>;
}

const migrateCommand: CommandDefinition = {
  name: 'migrate',
  description: 'Manage database migrations',
  subcommands: [
    {
      name: 'create',
      description: 'Create a new migration file',
      arguments: [{ name: 'name', description: 'Migration name', required: true }],
      options: [
        { name: '--template', short: '-t', description: 'Template type', choices: ['sql', 'ts'] },
      ],
      examples: [
        'migrate create add_users_table',
        'migrate create add_index --template sql',
      ],
      handler: createMigration,
    },
    {
      name: 'run',
      description: 'Execute pending migrations',
      options: [
        { name: '--env', short: '-e', description: 'Target environment', default: 'development' },
        { name: '--dry-run', description: 'Preview without executing', type: 'boolean' },
        { name: '--to', description: 'Migrate up to this version' },
      ],
      examples: [
        'migrate run',
        'migrate run --env staging --dry-run',
        'migrate run --to 20260314_001',
      ],
      handler: runMigrations,
    },
  ],
};

Task Automation Chaining

Copy
# Command chaining patterns for automation
# Sequential: Run migrations then seed
migrate run --env staging && migrate seed --env staging

# Conditional: Only seed if migration succeeds
migrate run --env staging && migrate seed --env staging || echo "Migration failed"

# Pipeline: Generate migration from diff, then apply
schema diff --from prod --to dev | migrate create --from-diff | migrate run --dry-run

# Batch: Run same command across environments
for env in dev staging; do
  migrate run --env "$env" --confirm
done

Configuration

Parameter	Description	Default
parser	Argument parser library (commander, yargs, clap)	Auto-detect
style	Command style (posix, gnu, windows)	posix
completion_shells	Generate completions for (bash, zsh, fish)	["bash", "zsh"]
help_format	Help output style (standard, man-page, minimal)	standard
strict_mode	Reject unknown flags	true
color_output	Use colored terminal output	auto

Best Practices

1. Design commands around user intent verbs, not internal operations. Name commands after what the user wants to accomplish: deploy, migrate, test — not after the implementation: execute-pipeline, run-script. Subcommands should be specific actions: migrate create, migrate run, migrate rollback. This makes the CLI discoverable without reading documentation.

2. Provide progressive disclosure of complexity. The simplest invocation should work with sensible defaults: migrate run runs pending migrations against the development database. Advanced options add specificity: migrate run --env staging --to 20260314 --dry-run. Never require complex flags for common operations. Power users discover options through --help, but the basic command must work immediately.

3. Include at least two usage examples in every command's help text. Examples teach faster than flag descriptions. Show one basic invocation and one advanced invocation. Use realistic values, not placeholders: migrate create add_users_table is clearer than migrate create <name>. Developers copy-paste examples more often than they construct commands from flag documentation.

4. Make destructive commands require explicit confirmation. Commands that delete data, modify production, or are irreversible should require a --confirm or --force flag, or prompt interactively for confirmation. Show what will happen before asking for confirmation: "This will rollback 3 migrations affecting tables: users, orders, payments. Continue? [y/N]." Default to the safe option (No).

5. Output structured data alongside human-readable text. Support --json and --quiet flags so automation can parse output while humans get readable formatting. In JSON mode, output only the data object to stdout. In quiet mode, output nothing on success and only errors on failure. In default mode, use tables, colors, and progress indicators. This makes every command both human-friendly and automation-ready.

Common Issues

Command names conflict with system utilities. Naming your tool test, install, or run collides with common shell builtins and system binaries. Check for conflicts with which <name> and type <name> before choosing a command name. Use prefixed naming (myapp-migrate) or a parent command namespace (myapp migrate) to avoid collisions. If a name conflict is unavoidable, document it in the installation instructions.

Help text is too long and users cannot find the option they need. Commands with 20+ options produce walls of text that obscure the important options. Group options by category (required, common, advanced) in the help output. Use a separate --help-all flag for exhaustive documentation. Put rarely-used options in configuration files instead of command-line flags to keep the help text scannable.

Flag parsing behaves differently across shells. A command like tool --name "hello world" works in bash but may parse differently in PowerShell or fish. Use a battle-tested argument parser library rather than manual parsing. Avoid relying on shell-specific quoting behavior. Document quoting requirements for each supported shell when passing values with spaces or special characters.