mytool [global-options] <command> [command-options] [arguments]

Examples:
  git commit -m "message"
  docker container ls --all
  npm run build -- --watch

Short flags: -v, -h, -o
Long flags: --verbose, --help, --output
Boolean flags: --no-cache, --force
Value flags: --output=file.txt, --format json

Error: Could not read configuration file
  Path: ~/.config/mytool/config.yaml
  Reason: Permission denied

Suggestion: Run 'chmod 644 ~/.config/mytool/config.yaml' to fix permissions

0   - Success
1   - General error
2   - Misuse of command (invalid arguments)
64  - Command line usage error
65  - Data format error
66  - Cannot open input file
73  - Cannot create output file
74  - I/O error
130 - Interrupted (Ctrl+C)

// Commander.js
import { Command } from 'commander';

const program = new Command();
program
  .name('mytool')
  .description('A CLI tool description')
  .version('1.0.0')
  .option('-v, --verbose', 'Enable verbose output')
  .option('-o, --output <file>', 'Output file path')
  .argument('<input>', 'Input file')
  .action((input, options) => {
    // Handle command
  });

// Yargs
import yargs from 'yargs';

const argv = yargs(process.argv.slice(2))
  .command('build <project>', 'Build a project', (yargs) => {
    return yargs.positional('project', { describe: 'Project name' });
  })
  .option('verbose', { alias: 'v', type: 'boolean' })
  .help()
  .parse();

# Click
import click

@click.command()
@click.option('--verbose', '-v', is_flag=True, help='Enable verbose output')
@click.option('--output', '-o', type=click.Path(), help='Output file')
@click.argument('input_file', type=click.Path(exists=True))
def main(verbose, output, input_file):
    """Process INPUT_FILE and generate output."""
    pass

# Argparse
import argparse

parser = argparse.ArgumentParser(description='Process files')
parser.add_argument('input', help='Input file path')
parser.add_argument('-o', '--output', help='Output file path')
parser.add_argument('-v', '--verbose', action='store_true')
args = parser.parse_args()

// Cobra
var rootCmd = &cobra.Command{
    Use:   "mytool",
    Short: "A brief description",
    Run: func(cmd *cobra.Command, args []string) {
        // Main logic
    },
}

func init() {
    rootCmd.PersistentFlags().BoolVarP(&verbose, "verbose", "v", false, "verbose output")
    rootCmd.Flags().StringVarP(&output, "output", "o", "", "output file")
}

// Input validation with helpful errors
function validateInput(options: Options): void {
  if (!options.input) {
    throw new ValidationError(
      'Missing required argument: input',
      'Provide an input file: mytool <input-file>'
    );
  }

  if (!fs.existsSync(options.input)) {
    throw new ValidationError(
      `Input file not found: ${options.input}`,
      'Check that the file exists and the path is correct'
    );
  }

  if (options.format && !['json', 'yaml', 'xml'].includes(options.format)) {
    throw new ValidationError(
      `Invalid format: ${options.format}`,
      'Supported formats: json, yaml, xml'
    );
  }
}

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = new Server(
  { name: 'my-mcp-server', version: '1.0.0' },
  { capabilities: { tools: {}, resources: {} } }
);

// Tool registration
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: 'search_files',
      description: 'Search for files matching a pattern',
      inputSchema: {
        type: 'object',
        properties: {
          pattern: { type: 'string', description: 'Glob pattern' },
          path: { type: 'string', description: 'Search directory' }
        },
        required: ['pattern']
      }
    }
  ]
}));

// Tool execution
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;

  switch (name) {
    case 'search_files':
      return await searchFiles(args.pattern, args.path);
    default:
      throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
  }
});

// Start server
const transport = new StdioServerTransport();
await server.connect(transport);

interface ToolDefinition {
  name: string;           // Unique tool identifier
  description: string;    // Human-readable description for AI
  inputSchema: {          // JSON Schema for parameters
    type: 'object';
    properties: Record<string, PropertySchema>;
    required?: string[];
  };
}

// Example tool with comprehensive schema
const readFileTool: ToolDefinition = {
  name: 'read_file',
  description: 'Read contents of a file. Returns file content as text.',
  inputSchema: {
    type: 'object',
    properties: {
      path: {
        type: 'string',
        description: 'Absolute path to the file to read'
      },
      encoding: {
        type: 'string',
        enum: ['utf8', 'base64', 'hex'],
        default: 'utf8',
        description: 'File encoding'
      },
      maxLines: {
        type: 'number',
        description: 'Maximum lines to read (omit for all)'
      }
    },
    required: ['path']
  }
};

// Resources provide dynamic content access
server.setRequestHandler(ListResourcesRequestSchema, async () => ({
  resources: [
    {
      uri: 'file:///workspace/config.json',
      name: 'Project Configuration',
      mimeType: 'application/json'
    },
    {
      uri: 'api://github/repos/{owner}/{repo}',
      name: 'GitHub Repository',
      mimeType: 'application/json'
    }
  ]
}));

server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
  const { uri } = request.params;

  if (uri.startsWith('file://')) {
    const path = uri.slice(7);
    const content = await fs.readFile(path, 'utf-8');
    return {
      contents: [{ uri, mimeType: 'text/plain', text: content }]
    };
  }

  throw new McpError(ErrorCode.InvalidRequest, `Unknown resource: ${uri}`);
});

// Server-side
const transport = new StdioServerTransport();
await server.connect(transport);

// Client-side (spawning server process)
const transport = new StdioClientTransport({
  command: 'node',
  args: ['./my-server.js']
});

// For web-based MCP servers
import express from 'express';
import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';

const app = express();

app.get('/sse', async (req, res) => {
  const transport = new SSEServerTransport('/messages', res);
  await server.connect(transport);
});

app.post('/messages', async (req, res) => {
  // Handle incoming messages
});

// Input validation
function validatePath(path: string): void {
  // Prevent path traversal
  const normalized = path.normalize(path);
  if (normalized.includes('..')) {
    throw new McpError(ErrorCode.InvalidParams, 'Path traversal not allowed');
  }

  // Check against allowed directories
  const allowed = ['/workspace', '/tmp'];
  if (!allowed.some(dir => normalized.startsWith(dir))) {
    throw new McpError(ErrorCode.InvalidParams, 'Path outside allowed directories');
  }
}

// Rate limiting
const rateLimiter = new RateLimiter({ maxRequests: 100, windowMs: 60000 });

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (!rateLimiter.check()) {
    throw new McpError(ErrorCode.InvalidRequest, 'Rate limit exceeded');
  }
  // ... handle request
});

// Using ora for spinners
import ora from 'ora';

const spinner = ora('Loading...').start();
try {
  await longOperation();
  spinner.succeed('Complete');
} catch (error) {
  spinner.fail('Failed');
}

// Progress bar with cli-progress
import { SingleBar, Presets } from 'cli-progress';

const bar = new SingleBar({}, Presets.shades_classic);
bar.start(100, 0);
for (let i = 0; i <= 100; i++) {
  bar.update(i);
  await delay(50);
}
bar.stop();

// Using Inquirer.js
import inquirer from 'inquirer';

const answers = await inquirer.prompt([
  {
    type: 'input',
    name: 'name',
    message: 'Project name:',
    validate: (input) => input.length > 0 || 'Name is required'
  },
  {
    type: 'list',
    name: 'template',
    message: 'Select template:',
    choices: ['React', 'Vue', 'Angular', 'Svelte']
  },
  {
    type: 'confirm',
    name: 'typescript',
    message: 'Use TypeScript?',
    default: true
  }
]);

// Using cli-table3
import Table from 'cli-table3';

const table = new Table({
  head: ['Name', 'Status', 'Last Updated'],
  style: { head: ['cyan'] }
});

table.push(
  ['api-server', 'Running', '2 minutes ago'],
  ['worker', 'Stopped', '1 hour ago'],
  ['scheduler', 'Running', '5 minutes ago']
);

console.log(table.toString());

import path from 'path';
import os from 'os';

// Use path.join for cross-platform paths
const configPath = path.join(os.homedir(), '.config', 'mytool', 'config.json');

// Handle Windows drive letters
function normalizePath(inputPath: string): string {
  return inputPath.replace(/\\/g, '/');
}

// Platform-specific config directories
function getConfigDir(): string {
  switch (process.platform) {
    case 'win32':
      return process.env.APPDATA || path.join(os.homedir(), 'AppData', 'Roaming');
    case 'darwin':
      return path.join(os.homedir(), 'Library', 'Application Support');
    default:
      return process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
  }
}

#!/usr/bin/env bash
# Use /usr/bin/env for portability

# Check for required commands
command -v jq >/dev/null 2>&1 || { echo "jq is required"; exit 1; }

# Portable string manipulation (avoid bash-specific features for POSIX)
# Bash-specific: ${var,,} for lowercase
# Portable: $(echo "$var" | tr '[:upper:]' '[:lower:]')

# Handle different sed versions (GNU vs BSD)
if sed --version 2>/dev/null | grep -q GNU; then
  sed -i 's/old/new/' file.txt
else
  sed -i '' 's/old/new/' file.txt  # BSD sed
fi

import supportsColor from 'supports-color';

// Check color support
const useColors = supportsColor.stdout && supportsColor.stdout.hasBasic;

// Check if running in TTY
const isInteractive = process.stdin.isTTY && process.stdout.isTTY;

// Fallback for non-interactive mode
if (!isInteractive) {
  // Use simple output without prompts
  console.log(JSON.stringify(result));
} else {
  // Use interactive prompts and colors
  displayInteractiveUI(result);
}

// Test argument parsing
describe('CLI argument parsing', () => {
  it('should parse input file argument', () => {
    const args = parseArgs(['input.txt']);
    expect(args.input).toBe('input.txt');
  });

  it('should parse output flag', () => {
    const args = parseArgs(['input.txt', '-o', 'output.txt']);
    expect(args.output).toBe('output.txt');
  });
});

import { execSync, spawn } from 'child_process';

describe('CLI integration', () => {
  it('should process file and output JSON', () => {
    const result = execSync('node ./cli.js input.txt --json', {
      encoding: 'utf-8'
    });
    const output = JSON.parse(result);
    expect(output.success).toBe(true);
  });

  it('should return error code for missing file', () => {
    expect(() => {
      execSync('node ./cli.js nonexistent.txt');
    }).toThrow();
  });
});

// Capture and compare CLI output
describe('CLI output snapshots', () => {
  it('should match help output', () => {
    const output = execSync('node ./cli.js --help', { encoding: 'utf-8' });
    expect(output).toMatchSnapshot();
  });
});

import { Client } from '@modelcontextprotocol/sdk/client/index.js';

describe('MCP Server', () => {
  let client: Client;

  beforeAll(async () => {
    // Connect to test server
    client = new Client({ name: 'test-client', version: '1.0.0' }, {});
    await client.connect(transport);
  });

  it('should list available tools', async () => {
    const tools = await client.listTools();
    expect(tools.tools).toContainEqual(
      expect.objectContaining({ name: 'read_file' })
    );
  });

  it('should execute tool successfully', async () => {
    const result = await client.callTool({
      name: 'read_file',
      arguments: { path: '/tmp/test.txt' }
    });
    expect(result.content[0].text).toContain('test content');
  });
});

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

# Using pkg
npx pkg . --targets node18-linux-x64,node18-macos-x64,node18-win-x64

# Output: mytool-linux, mytool-macos, mytool-win.exe

# pyproject.toml
[project.scripts]
mytool = "mytool.cli:main"

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

pyinstaller --onefile --name mytool cli.py

# .goreleaser.yml
builds:
  - main: ./cmd/mytool
    binary: mytool
    goos: [linux, darwin, windows]
    goarch: [amd64, arm64]

archives:
  - format_overrides:
      - goos: windows
        format: zip

brews:
  - tap:
      owner: myorg
      name: homebrew-tap
    homepage: https://github.com/myorg/mytool
    description: My CLI tool

class Mytool < Formula
  desc "My CLI tool description"
  homepage "https://github.com/myorg/mytool"
  url "https://github.com/myorg/mytool/archive/v1.0.0.tar.gz"
  sha256 "..."
  license "MIT"

  depends_on "node"

  def install
    system "npm", "install", *Language::Node.std_npm_install_args(libexec)
    bin.install_symlink Dir["#{libexec}/bin/*"]
  end

  test do
    assert_match "1.0.0", shell_output("#{bin}/mytool --version")
  end
end