Building CLIs in OpenAgents Control: Compact Guide

Category: guide
Purpose: Rapidly build, register, and deploy CLI tools for OpenAgents Control skills
Framework: FAB (Features, Advantages, Benefits)

🚀 Quick Start

Don't start from scratch. Use the standard pattern to build robust CLIs in minutes.

Create: mkdir -p .opencode/skills/{name}/scripts
Implement: Create skill-cli.ts (TypeScript) and router.sh (Bash)
Register: Add to registry.json
Run: bash .opencode/skills/{name}/router.sh help

🏗️ Core Architecture

Component	File	Purpose
Logic	`scripts/skill-cli.ts`	Type-safe implementation using `ts-node`. Handles args, logic, and output.
Router	`router.sh`	Universal entry point. Routes commands to the TS script.
Docs	`SKILL.md`	User guide, examples, and integration details.
Config	`registry.json`	Makes the skill discoverable and installable via `install.sh`.

⚡ Implementation Patterns

1. The Router (`router.sh`)

Why: Provides a consistent, dependency-free entry point for all environments.

#!/bin/bash
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

case "$1" in
    help|--help|-h)
        echo "Usage: bash router.sh <command>"
        ;;
    *)
        # Route to TypeScript implementation
        npx ts-node "$SCRIPT_DIR/scripts/skill-cli.ts" "$@"
        ;;
esac

2. The CLI Logic (`skill-cli.ts`)

Why: Type safety, async/await support, and rich ecosystem access.

#!/usr/bin/env ts-node

async function main() {
  const [command, ...args] = process.argv.slice(2);
  
  switch (command) {
    case 'action':
      await handleAction(args);
      break;
    default:
      console.log("Unknown command");
      process.exit(1);
  }
}

main().catch(console.error);

✅ Quality Checklist

Before shipping, verify your CLI delivers value:

Help Command: Does router.sh help provide clear, actionable usage info?
Error Handling: Do invalid inputs return helpful error messages (not stack traces)?
Performance: Does it start in < 1s? (Avoid heavy imports at top level)
Idempotency: Can commands be run multiple times safely?
Registry: Is it added to registry.json with correct paths?

🧠 Copywriting Principles for CLI Output

Apply content-creation principles to your CLI output:

Clarity: Use Active Voice. "Created file" (Good) vs "File has been created" (Bad).
Specificity: "Processed 5 files" (Good) vs "Processing complete" (Bad).
Action: Tell the user what to do next. "Run npm test to verify."

Reference: See .opencode/context/openagents-repo/guides/adding-skill.md for the full, detailed walkthrough.

building-cli-compact.md 2.8 KB History Raw