bun-cli

# Bun CLI Development

Build powerful, production-grade CLI tools with Bun. Master argument parsing, output formatting, error handling, subcommands, and testing patterns proven in production across the SideQuest marketplace.

## Quick Navigation

- **[Quick Start](#quick-start)** — Get a working CLI in 5 minutes
- **[Core Patterns](#core-patterns)** — Argument parsing, output, usage, errors, subcommands
- **[Advanced Features](#advanced-features)** — Dry-run, auto-commit, git integration
- **[Testing Your CLI](#testing-your-cli)** — Unit and integration test patterns
- **[Reference](#reference)** — Comprehensive pattern guide + Para Obsidian example (9/10)

---

## Quick Start

**Goal:** Build a CLI tool that feels natural to use and is easy to maintain.

### Minimal CLI Template

```typescript
#!/usr/bin/env bun

import { color } from "@side-quest/core/formatters";

function printUsage(): void {
  console.log(color("cyan", "My CLI Tool v1.0"));
  console.log("Usage: my-cli <command> [options]");
  console.log("  config    Show configuration");
  console.log("  help      Show this help");
}

async function main(): Promise<void> {
  const [, , command] = process.argv;

  if (!command || command === "help") {
    printUsage();
    return;
  }

  try {
    switch (command) {
      case "config":
        console.log("Config: {...}");
        break;
      default:
        console.error(`Unknown command: ${command}`);
        process.exit(1);
    }
  } catch (error) {
    console.error("Error:", error instanceof Error ? error.message : error);
    process.exit(1);
  }
}

main();
```

---

## Core Patterns

### 1. Argument Parsing

The marketplace standard uses **manual parsing** (not external libraries). This keeps CLIs simple, dependency-light, and predictable.

**Handle three flag formats:**
- `--flag value` — Spaced syntax
- `--flag=value` — Equals syntax
- `--flag` — Boolean flag

```typescript
function parseArgs(argv: string[]) {
  const positional: string[] = [];