Real-World Project - Building a Typed CLI Tool

The Deployment Process That Wasted 3 Hours Every Day

Monday morning, 9:00 AM. Deploy day. Same ritual every week:

1. Pull latest code from 4 repositories

2. Run tests in each repo

3. Build Docker images (names always typo'd)

4. Tag images with version

5. Push to registry

6. Update Kubernetes manifests

7. Apply to clusters (dev, staging, prod)

8. Wait for rollout

9. Verify health checks

10. Update Slack with deployment status

Time: 45 minutes per deployment. Deployments per day: 4. Total: 3 hours of manual, error-prone work.

Mistakes were common:

• March 15: Deployed wrong image tag to production (20-minute outage)

• April 3: Forgot to update manifest, old version deployed

• May 8: Typo in image name, deployment failed at 6 PM

Our DevOps lead: "We need automation. Can't keep doing this manually."

I built a TypeScript CLI tool: deploy-cli. One command:

deploy --env production --version 2.4.1

Result:

• Deployments: 45 minutes → 8 minutes

• Errors: Common → zero in 6 months

• Time saved: 15 hours per week across team

This article shows you how to build production-grade CLI tools with TypeScript.

---

Project Setup

Initialize Project

mkdir deploy-cli
cd deploy-cli
npm init -y

Install Dependencies

# Core
npm install commander chalk ora
npm install --save-dev typescript @types/node

# For our use case
npm install dotenv js-yaml @octokit/rest
npm install --save-dev @types/js-yaml

TypeScript Configuration

// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

Package.json

{
  "name": "deploy-cli",
  "version": "1.0.0",
  "description": "Automated deployment CLI tool",
  "main": "dist/index.js",
  "bin": {
    "deploy": "./dist/index.js"
  },
  "scripts": {
    "build": "tsc",
    "dev": "tsc --watch",
    "start": "node dist/index.js"
  },
  "keywords": ["deployment", "cli", "automation"],
  "author": "Your Name",
  "license": "MIT"
}

---

Building the CLI

Main Entry Point

#!/usr/bin/env node

// src/index.ts
import { Command } from 'commander';
import chalk from 'chalk';
import { deploy } from './commands/deploy';
import { rollback } from './commands/rollback';
import { status } from './commands/status';

const program = new Command();

program
  .name('deploy')
  .description('Automated deployment tool')
  .version('1.0.0');

program
  .command('deploy')
  .description('Deploy application to specified environment')
  .option('-e, --env <environment>', 'Target environment (dev, staging, prod)')
  .option('-v, --version <version>', 'Application version to deploy')
  .option('-s, --service <service>', 'Service to deploy (default: all)')
  .option('--skip-tests', 'Skip running tests')
  .option('--dry-run', 'Simulate deployment without executing')
  .action(deploy);

program
  .command('rollback')
  .description('Rollback to previous deployment')
  .option('-e, --env <environment>', 'Target environment')
  .option('-s, --service <service>', 'Service to rollback')
  .action(rollback);

program
  .command('status')
  .description('Check deployment status')
  .option('-e, --env <environment>', 'Environment to check')
  .action(status);

program.parse(process.argv);

if (!process.argv.slice(2).length) {
  program.outputHelp();
}

---

Type Definitions

// src/types/index.ts

export interface DeployOptions {
  env: 'dev' | 'staging' | 'prod';
  version: string;
  service?: string;
  skipTests?: boolean;
  dryRun?: boolean;
}

export interface Service {
  name: string;
  repository: string;
  dockerfile: string;
  manifestPath: string;
}

export interface DeploymentConfig {
  services: Service[];
  dockerRegistry: string;
  kubernetesContext: {
    dev: string;
    staging: string;
    prod: string;
  };
}

export interface DeploymentResult {
  success: boolean;
  service: string;
  version: string;
  duration: number;
  error?: string;
}

---

Configuration Management

// src/config/index.ts
import fs from 'fs';
import path from 'path';
import yaml from 'js-yaml';
import { DeploymentConfig } from '../types';

export function loadConfig(): DeploymentConfig {
  const configPath = path.join(process.cwd(), 'deploy.config.yaml');
  
  if (!fs.existsSync(configPath)) {
    throw new Error('deploy.config.yaml not found in current directory');
  }
  
  const fileContents = fs.readFileSync(configPath, 'utf8');
  const config = yaml.load(fileContents) as DeploymentConfig;
  
  validateConfig(config);
  
  return config;
}

function validateConfig(config: DeploymentConfig): void {
  if (!config.services || config.services.length === 0) {
    throw new Error('No services defined in configuration');
  }
  
  if (!config.dockerRegistry) {
    throw new Error('Docker registry not specified');
  }
  
  for (const service of config.services) {
    if (!service.name || !service.repository) {
      throw new Error(`Invalid service configuration: ${JSON.stringify(service)}`);
    }
  }
}

Example config file:

# deploy.config.yaml
dockerRegistry: registry.example.com
kubernetesContext:
  dev: dev-cluster
  staging: staging-cluster
  prod: prod-cluster

services:
  - name: api
    repository: github.com/company/api
    dockerfile: Dockerfile
    manifestPath: k8s/api.yaml
  
  - name: frontend
    repository: github.com/company/frontend
    dockerfile: Dockerfile
    manifestPath: k8s/frontend.yaml

---

Command Implementation

// src/commands/deploy.ts
import chalk from 'chalk';
import ora from 'ora';
import { DeployOptions, DeploymentResult } from '../types';
import { loadConfig } from '../config';
import { runTests } from '../utils/tests';
import { buildImage, pushImage } from '../utils/docker';
import { updateManifest, applyManifest } from '../utils/kubernetes';
import { notifySlack } from '../utils/notifications';

export async function deploy(options: DeployOptions): Promise<void> {
  console.log(chalk.bold.blue('\n🚀 Starting deployment...\n'));
  
  // Validate options
  if (!options.env) {
    console.error(chalk.red('Error: Environment is required (--env)'));
    process.exit(1);
  }
  
  if (!options.version) {
    console.error(chalk.red('Error: Version is required (--version)'));
    process.exit(1);
  }
  
  const config = loadConfig();
  const services = options.service 
    ? config.services.filter(s => s.name === options.service)
    : config.services;
  
  if (services.length === 0) {
    console.error(chalk.red(`Error: Service "${options.service}" not found`));
    process.exit(1);
  }
  
  const startTime = Date.now();
  const results: DeploymentResult[] = [];
  
  // Deploy each service
  for (const service of services) {
    const result = await deployService(service, options, config);
    results.push(result);
    
    if (!result.success) {
      console.error(chalk.red(`\n❌ Deployment failed for ${service.name}`));
      console.error(chalk.red(result.error));
      process.exit(1);
    }
  }
  
  // Summary
  const totalDuration = Date.now() - startTime;
  console.log(chalk.bold.green('\n✅ Deployment completed successfully!\n'));
  console.log(chalk.gray(`Total time: ${(totalDuration / 1000).toFixed(2)}s`));
  
  // Notify
  await notifySlack({
    environment: options.env,
    version: options.version,
    services: results.map(r => r.service),
    duration: totalDuration
  });
}

async function deployService(
  service: any,
  options: DeployOptions,
  config: any
): Promise<DeploymentResult> {
  const startTime = Date.now();
  
  try {
    console.log(chalk.bold(`\n📦 Deploying ${service.name}...\n`));
    
    // Step 1: Run tests
    if (!options.skipTests) {
      const testSpinner = ora('Running tests...').start();
      await runTests(service.repository);
      testSpinner.succeed('Tests passed');
    }
    
    // Step 2: Build Docker image
    if (!options.dryRun) {
      const buildSpinner = ora('Building Docker image...').start();
      const imageName = `${config.dockerRegistry}/${service.name}:${options.version}`;
      await buildImage(service.repository, imageName);
      buildSpinner.succeed(`Built ${imageName}`);
      
      // Step 3: Push image
      const pushSpinner = ora('Pushing to registry...').start();
      await pushImage(imageName);
      pushSpinner.succeed('Image pushed');
      
      // Step 4: Update Kubernetes manifest
      const manifestSpinner = ora('Updating manifest...').start();
      await updateManifest(service.manifestPath, imageName);
      manifestSpinner.succeed('Manifest updated');
      
      // Step 5: Apply to cluster
      const deploySpinner = ora(`Deploying to ${options.env}...`).start();
      const context = config.kubernetesContext[options.env];
      await applyManifest(service.manifestPath, context);
      deploySpinner.succeed(`Deployed to ${options.env}`);
    } else {
      console.log(chalk.yellow('Dry run - skipping actual deployment'));
    }
    
    const duration = Date.now() - startTime;
    
    return {
      success: true,
      service: service.name,
      version: options.version,
      duration
    };
    
  } catch (error) {
    return {
      success: false,
      service: service.name,
      version: options.version,
      duration: Date.now() - startTime,
      error: error instanceof Error ? error.message : 'Unknown error'
    };
  }
}

---

Utility Functions

Docker Operations

// src/utils/docker.ts
import { exec } from 'child_process';
import { promisify } from 'util';

const execAsync = promisify(exec);

export async function buildImage(
  repoPath: string, 
  imageName: string
): Promise<void> {
  const command = `docker build -t ${imageName} ${repoPath}`;
  
  try {
    await execAsync(command);
  } catch (error) {
    throw new Error(`Failed to build image: ${error}`);
  }
}

export async function pushImage(imageName: string): Promise<void> {
  const command = `docker push ${imageName}`;
  
  try {
    await execAsync(command);
  } catch (error) {
    throw new Error(`Failed to push image: ${error}`);
  }
}

export async function tagImage(
  sourceName: string,
  targetName: string
): Promise<void> {
  const command = `docker tag ${sourceName} ${targetName}`;
  
  try {
    await execAsync(command);
  } catch (error) {
    throw new Error(`Failed to tag image: ${error}`);
  }
}

Kubernetes Operations

// src/utils/kubernetes.ts
import fs from 'fs';
import yaml from 'js-yaml';
import { exec } from 'child_process';
import { promisify } from 'util';

const execAsync = promisify(exec);

export async function updateManifest(
  manifestPath: string,
  imageName: string
): Promise<void> {
  const manifest = yaml.load(fs.readFileSync(manifestPath, 'utf8')) as any;
  
  // Update image in deployment spec
  if (manifest.kind === 'Deployment') {
    manifest.spec.template.spec.containers[0].image = imageName;
  }
  
  fs.writeFileSync(manifestPath, yaml.dump(manifest));
}

export async function applyManifest(
  manifestPath: string,
  context: string
): Promise<void> {
  const command = `kubectl apply -f ${manifestPath} --context=${context}`;
  
  try {
    const { stdout } = await execAsync(command);
    console.log(stdout);
  } catch (error) {
    throw new Error(`Failed to apply manifest: ${error}`);
  }
}

export async function rolloutStatus(
  deploymentName: string,
  namespace: string,
  context: string
): Promise<boolean> {
  const command = `kubectl rollout status deployment/${deploymentName} -n ${namespace} --context=${context}`;
  
  try {
    await execAsync(command);
    return true;
  } catch (error) {
    return false;
  }
}

Test Runner

// src/utils/tests.ts
import { exec } from 'child_process';
import { promisify } from 'util';

const execAsync = promisify(exec);

export async function runTests(repoPath: string): Promise<void> {
  const command = `cd ${repoPath} && npm test`;
  
  try {
    await execAsync(command);
  } catch (error) {
    throw new Error(`Tests failed: ${error}`);
  }
}

Notifications

// src/utils/notifications.ts
import fetch from 'node-fetch';

interface SlackNotification {
  environment: string;
  version: string;
  services: string[];
  duration: number;
}

export async function notifySlack(
  notification: SlackNotification
): Promise<void> {
  const webhookUrl = process.env.SLACK_WEBHOOK_URL;
  
  if (!webhookUrl) {
    return; // Skip if not configured
  }
  
  const message = {
    text: `🚀 Deployment Complete`,
    blocks: [
      {
        type: 'section',
        text: {
          type: 'mrkdwn',
          text: `*Deployment Complete*\n*Environment:* ${notification.environment}\n*Version:* ${notification.version}\n*Services:* ${notification.services.join(', ')}\n*Duration:* ${(notification.duration / 1000).toFixed(2)}s`
        }
      }
    ]
  };
  
  await fetch(webhookUrl, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(message)
  });
}

---

Error Handling

// src/utils/errors.ts
import chalk from 'chalk';

export class DeploymentError extends Error {
  constructor(
    message: string,
    public service?: string,
    public step?: string
  ) {
    super(message);
    this.name = 'DeploymentError';
  }
}

export function handleError(error: unknown): never {
  if (error instanceof DeploymentError) {
    console.error(chalk.red(`\n❌ Deployment Error`));
    if (error.service) {
      console.error(chalk.red(`Service: ${error.service}`));
    }
    if (error.step) {
      console.error(chalk.red(`Step: ${error.step}`));
    }
    console.error(chalk.red(`Message: ${error.message}\n`));
  } else if (error instanceof Error) {
    console.error(chalk.red(`\n❌ Error: ${error.message}\n`));
  } else {
    console.error(chalk.red('\n❌ Unknown error occurred\n'));
  }
  
  process.exit(1);
}

---

Building and Installing

Build

npm run build

Local Installation

npm link

Now deploy command is available globally:

deploy --help
deploy deploy --env staging --version 1.2.3
deploy status --env prod

Distribution

npm publish

Users install with:

npm install -g deploy-cli

---

Testing the CLI

// src/__tests__/deploy.test.ts
import { deploy } from '../commands/deploy';
import * as docker from '../utils/docker';
import * as k8s from '../utils/kubernetes';

jest.mock('../utils/docker');
jest.mock('../utils/kubernetes');

describe('deploy command', () => {
  it('should deploy successfully with valid options', async () => {
    const mockBuildImage = jest.spyOn(docker, 'buildImage').mockResolvedValue();
    const mockPushImage = jest.spyOn(docker, 'pushImage').mockResolvedValue();
    const mockApplyManifest = jest.spyOn(k8s, 'applyManifest').mockResolvedValue();
    
    await deploy({
      env: 'dev',
      version: '1.0.0',
      skipTests: true
    });
    
    expect(mockBuildImage).toHaveBeenCalled();
    expect(mockPushImage).toHaveBeenCalled();
    expect(mockApplyManifest).toHaveBeenCalled();
  });
  
  it('should throw error with invalid environment', async () => {
    await expect(deploy({
      env: 'invalid' as any,
      version: '1.0.0'
    })).rejects.toThrow();
  });
});

---

Your Challenge

Extend the CLI with new features:

// TODO: Add these commands:

// 1. deploy logs --env prod --service api --tail 100
//    - Fetch and display logs from deployed service

// 2. deploy scale --env prod --service api --replicas 5
//    - Scale deployment to specified replicas

// 3. deploy health --env prod
//    - Check health of all services

// 4. deploy diff --version 1.2.3 --version 1.2.4
//    - Show differences between versions

// 5. deploy approve --env prod --version 1.2.3
//    - Require approval before prod deployments

// Requirements:
// - Full type safety
// - Error handling
// - Progress indicators (ora)
// - Colored output (chalk)
// - Proper exit codes

---

Key Takeaways

1. Commander.js - build CLI with options and commands

2. Chalk - colored terminal output

3. Ora - loading spinners

4. Type safety - strong typing for all operations

5. Config files - YAML for configuration

6. Error handling - custom error classes

7. Process execution - promisified exec for shell commands

8. npm bin - make CLI globally installable

---

What I Learned

Manual deployments took 45 minutes each. 4 per day = 3 hours of tedious work. Plus constant errors - wrong tags, typos, forgotten steps.

I built deploy-cli in 2 days:

deploy --env production --version 2.4.1

Result:

• Deployments: 45 minutes → 8 minutes

• Errors: zero in 6 months

• Time saved: 15 hours per week

TypeScript was essential:

• Type-safe options: Can't pass invalid environment

• Compile-time checks: Catch errors before running

• Autocomplete: IDE knows all available options

• Refactoring: Rename functions, find all usages

Before the CLI, deployments were error-prone manual processes. After the CLI, they're automated, consistent, and fast.

The lesson: Repetitive manual tasks are automation opportunities. If you're doing it multiple times a day, build a tool. TypeScript makes that tool reliable and maintainable.

Turn your daily friction into automated tools. Reclaim your time.

---

Next: Building a Real-World REST API

In the final article, we'll build a complete production-ready REST API with TypeScript and Express. You'll learn the architecture that serves 2 million requests per day with 99.9% uptime.