Building CLI Tools with AI: From Script to Product

Command-line tools remain essential for developers. They're fast, scriptable, and powerful. Building a good CLI requires attention to user experience details that AI can help you get right from the start.

Why Build CLI Tools?#

Automation: Script repetitive tasks
Integration: Connect systems and workflows
Distribution: Share tools easily
Productivity: Fast interaction without UI overhead

Getting Started#

Project Setup#

AI helps scaffold a proper CLI project:

Create a Node.js CLI project structure:

Name: myctl
Features:
- TypeScript
- Subcommands (init, build, deploy)
- Configuration file support
- Environment variables
- Help text and documentation

Include:
- package.json with bin configuration
- tsconfig.json
- Project structure
- Basic command implementations

Basic Command Structure#

// src/cli.ts
import { Command } from 'commander';
import { version } from '../package.json';

const program = new Command();

program
  .name('myctl')
  .description('My awesome CLI tool')
  .version(version);

program
  .command('init')
  .description('Initialize a new project')
  .option('-t, --template <type>', 'project template', 'default')
  .action(async (options) => {
    await initProject(options);
  });

program
  .command('build')
  .description('Build the project')
  .option('-w, --watch', 'watch for changes')
  .option('-p, --production', 'production build')
  .action(async (options) => {
    await buildProject(options);
  });

program.parse();

User Experience Patterns#

Interactive Prompts#

Implement interactive prompts for project initialization:

Questions:
1. Project name (validate: no spaces, lowercase)
2. Description
3. Template (choice: minimal, full, api)
4. Include testing? (confirm)
5. Package manager (choice: npm, yarn, pnpm)

Use inquirer or prompts library.
Show defaults and allow skipping with flags.

import inquirer from 'inquirer';

async function interactiveInit(defaults: Partial<InitOptions>) {
  const answers = await inquirer.prompt([
    {
      type: 'input',
      name: 'name',
      message: 'Project name:',
      default: defaults.name || path.basename(process.cwd()),
      validate: (input) => /^[a-z0-9-]+$/.test(input) || 'Use lowercase letters, numbers, and hyphens only'
    },
    {
      type: 'list',
      name: 'template',
      message: 'Select template:',
      choices: ['minimal', 'full', 'api'],
      default: defaults.template
    },
    {
      type: 'confirm',
      name: 'testing',
      message: 'Include testing setup?',
      default: true
    }
  ]);

  return answers;
}

Progress Indicators#

import ora from 'ora';

async function buildProject(options: BuildOptions) {
  const spinner = ora('Building project...').start();

  try {
    spinner.text = 'Compiling TypeScript...';
    await compileTypeScript();

    spinner.text = 'Bundling assets...';
    await bundleAssets();

    spinner.text = 'Optimizing...';
    await optimize();

    spinner.succeed('Build complete!');
  } catch (error) {
    spinner.fail(`Build failed: ${error.message}`);
    process.exit(1);
  }
}

Colored Output#

import chalk from 'chalk';

function logInfo(message: string) {
  console.log(chalk.blue('ℹ'), message);
}

function logSuccess(message: string) {
  console.log(chalk.green('✓'), message);
}

function logWarning(message: string) {
  console.log(chalk.yellow('⚠'), message);
}

function logError(message: string) {
  console.error(chalk.red('✗'), message);
}

// Usage
logSuccess('Project created successfully!');
logInfo(`Next steps:
  ${chalk.cyan('cd')} ${projectName}
  ${chalk.cyan('npm install')}
  ${chalk.cyan('npm run dev')}
`);

Tables and Lists#

import Table from 'cli-table3';

function displayProjects(projects: Project[]) {
  const table = new Table({
    head: ['Name', 'Status', 'Last Deploy'],
    colWidths: [30, 15, 25]
  });

  projects.forEach(project => {
    table.push([
      project.name,
      project.status === 'active' ? chalk.green('Active') : chalk.gray('Inactive'),
      project.lastDeploy || 'Never'
    ]);
  });

  console.log(table.toString());
}

Configuration Management#

Config File Support#

Implement configuration file support:

Locations to check (in order):
1. --config flag
2. .myctlrc.json in current directory
3. myctl.config.js in current directory
4. ~/.myctlrc (global config)

Support:
- JSON and JavaScript formats
- Environment variable expansion
- Schema validation
- Config merging (local + global)

import { cosmiconfig } from 'cosmiconfig';
import { z } from 'zod';

const configSchema = z.object({
  apiUrl: z.string().url(),
  token: z.string().optional(),
  defaults: z.object({
    template: z.enum(['minimal', 'full', 'api']).default('minimal'),
    packageManager: z.enum(['npm', 'yarn', 'pnpm']).default('npm')
  }).optional()
});

type Config = z.infer<typeof configSchema>;

async function loadConfig(): Promise<Config> {
  const explorer = cosmiconfig('myctl');
  const result = await explorer.search();

  if (!result) {
    return configSchema.parse({});
  }

  // Expand environment variables
  const expanded = expandEnvVars(result.config);

  return configSchema.parse(expanded);
}

Environment Variables#

import dotenv from 'dotenv';

// Load .env files
dotenv.config();

const config = {
  apiToken: process.env.MYCTL_TOKEN,
  apiUrl: process.env.MYCTL_API_URL || 'https://api.myctl.dev',
  debug: process.env.MYCTL_DEBUG === 'true'
};

// Validate required variables
if (!config.apiToken) {
  console.error(chalk.red('Error: MYCTL_TOKEN environment variable is required'));
  console.error(chalk.gray('Set it with: export MYCTL_TOKEN=your-token'));
  process.exit(1);
}

Error Handling#

User-Friendly Errors#

class CLIError extends Error {
  constructor(
    message: string,
    public readonly code: string,
    public readonly suggestions?: string[]
  ) {
    super(message);
  }
}

function handleError(error: unknown) {
  if (error instanceof CLIError) {
    console.error(chalk.red(`Error [${error.code}]: ${error.message}`));

    if (error.suggestions?.length) {
      console.error(chalk.yellow('\nSuggestions:'));
      error.suggestions.forEach(s => console.error(`  • ${s}`));
    }

    process.exit(1);
  }

  if (error instanceof z.ZodError) {
    console.error(chalk.red('Configuration error:'));
    error.errors.forEach(e => {
      console.error(`  ${e.path.join('.')}: ${e.message}`);
    });
    process.exit(1);
  }

  // Unexpected error
  console.error(chalk.red('Unexpected error:'), error);
  if (process.env.DEBUG) {
    console.error(error);
  }
  process.exit(1);
}

Testing CLI Tools#

Unit Testing Commands#

Generate tests for this CLI command:

```typescript
async function deployCommand(options: DeployOptions) {
  const config = await loadConfig();
  const project = await resolveProject(options.project);
  await validateProject(project);
  await build(project);
  const result = await deploy(project, options.environment);
  return result;
}

Test:

Missing project
Invalid configuration
Build failure
Deploy failure
Successful deploy

Use Jest with mocked dependencies.


### Integration Testing

```typescript
import { exec } from 'child_process';
import { promisify } from 'util';

const execAsync = promisify(exec);

describe('myctl CLI', () => {
  it('should display help', async () => {
    const { stdout } = await execAsync('npx myctl --help');
    expect(stdout).toContain('Usage:');
    expect(stdout).toContain('Commands:');
  });

  it('should initialize project', async () => {
    const { stdout } = await execAsync(
      'npx myctl init --name test-project --template minimal --no-interactive',
      { cwd: tempDir }
    );
    expect(stdout).toContain('Project created');
    expect(fs.existsSync(path.join(tempDir, 'test-project'))).toBe(true);
  });
});

Distribution#

npm Publishing#

{
  "name": "myctl",
  "version": "1.0.0",
  "bin": {
    "myctl": "./dist/cli.js"
  },
  "files": [
    "dist"
  ],
  "engines": {
    "node": ">=18"
  }
}

Standalone Binaries#

Create standalone binaries using pkg:

Targets:
- macOS (x64, arm64)
- Linux (x64)
- Windows (x64)

Include:
- Package.json configuration
- Build script
- GitHub Release workflow

Advanced Patterns#

Plugin System#

Design a plugin system for the CLI:

Requirements:
- Plugins add new commands
- Plugins can hook into existing commands
- Plugins installed via npm
- Local plugins for project-specific commands

Provide:
- Plugin interface
- Plugin loading mechanism
- Plugin registration

Auto-Update#

import updateNotifier from 'update-notifier';
import pkg from '../package.json';

// Check for updates (non-blocking)
const notifier = updateNotifier({
  pkg,
  updateCheckInterval: 1000 * 60 * 60 * 24 // Daily
});

// Display notification if update available
notifier.notify({
  message: 'Update available: {currentVersion} → {latestVersion}\nRun {updateCommand} to update'
});

Conclusion#

Building CLI tools with AI assistance accelerates development while maintaining quality. AI helps with:

Initial scaffolding and structure
User experience patterns (prompts, spinners, colors)
Error handling and validation
Testing strategies
Distribution and updates

Start with a clear purpose, focus on user experience, and iterate based on feedback. A well-designed CLI becomes an indispensable tool in developers' workflows.

Share this article