Build production-grade CLI tools with Bun. Reference implementation covering argument parsing patterns (--flag value, --flag=value, --flag), dual markdown/JSON output, error handling, subcommands, and testing. Use when building CLIs, designing argument parsing, implementing command structures, reviewing CLI quality, or learning Bun CLI best practices.
View on GitHubnathanvale/side-quest-marketplace
dev-toolkit
February 4, 2026
Select agents to install to:
npx add-skill https://github.com/nathanvale/side-quest-marketplace/blob/main/plugins/dev-toolkit/skills/bun-cli/SKILL.md -a claude-code --skill bun-cliInstallation paths:
.claude/skills/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[] = [];