Claude Skill

cli-framework-oclif-ink

Modern CLI development combining oclif's command framework with Ink's React-based terminal rendering

LLM Mart · 0 points · 1 views 0 listing impressions 0 install-command copies
Download agents-inc-skills-dist_plugins_cli-framework-oclif-ink_skills_cli-framework-oclif-ink-707467a.zip · 18 KB

Install

skills CLI npx skills add https://github.com/agents-inc/skills/tree/main/dist/plugins/cli-framework-oclif-ink/skills/cli-framework-oclif-ink
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install agents-inc-skills@llmmart
Git git clone https://github.com/agents-inc/skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole agents-inc/skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

oclif + Ink CLI Patterns

Quick Guide: Use oclif for command routing, flag/arg parsing, and plugin architecture. Use Ink for React-based interactive terminal UIs with Flexbox layout. Combine both when commands need rich stateful interfaces. Always await waitUntilExit() when rendering Ink from oclif commands. Use this.log() instead of console.log to preserve JSON output mode.


<critical_requirements>

CRITICAL: Before Using This Skill

(You MUST await waitUntilExit() after render() in oclif commands -- without it the process exits before the UI completes)

(You MUST use this.log() / this.warn() / this.error() in commands -- console.log breaks --json mode and test capture)

(You MUST wrap all text in <Text> components in Ink -- bare strings cause rendering errors)

(You MUST use useEffect cleanup to cancel async operations -- Ink components unmount when the user presses Ctrl+C)

</critical_requirements>


Auto-detection: oclif, @oclif/core, @oclif/test, Ink, ink, @inkjs/ui, Command class, Flags, Args, useInput, useApp, useFocus, render(), waitUntilExit, terminal UI, CLI command, ink-testing-library

When to use:

  • Building multi-command CLIs with flag/arg parsing
  • Creating interactive terminal UIs (wizards, dashboards, progress displays)
  • Combining command routing with rich React-based interfaces
  • Building plugin-extensible CLI architectures

When NOT to use:

  • Simple one-off scripts (plain Node.js suffices)
  • Basic prompts only (a lightweight prompt library suffices)
  • Performance-critical startup under 100ms (oclif adds ~200ms overhead)

Key patterns covered:

  • oclif command structure with typed flags, args, and output methods
  • Ink components, Flexbox layout, keyboard input, and focus management
  • Integration: rendering Ink from oclif commands with lifecycle management
  • @inkjs/ui pre-built components (Select, TextInput, Spinner, etc.)
  • Plugin architecture and lifecycle hooks
  • Multi-step wizards, progress indicators, and cancelable operations
  • Testing commands with @oclif/test and components with ink-testing-library



<decision_framework>

Decision Framework

Building a CLI?
|
+-> Need multiple commands / subcommands?
|   +-> YES -> oclif (multi-command mode)
|   +-> NO  -> oclif (single-command mode) or plain Node.js
|
+-> Need interactive terminal UI?
|   +-> Simple prompts (name, confirm)? -> Lightweight prompt library
|   +-> Complex stateful UI (wizard, dashboard)? -> Ink
|
+-> Need both routing AND complex UI?
    +-> YES -> oclif commands + Ink components
    +-> NO  -> Use whichever fits the primary need

Command File Organization

src/
  commands/           # oclif command classes (.ts files)
    init.ts
    config/
      get.ts          # mycli config get <key>
      set.ts          # mycli config set <key> <value>
  components/         # Ink React components (.tsx files)
    wizard.tsx
    progress.tsx
  hooks/              # oclif lifecycle hooks
    init.ts           # Runs before every command
    postrun.ts        # Runs after every command
  lib/                # Shared utilities

</decision_framework>


Detailed Resources:


<red_flags>

RED FLAGS

High Priority:

  • Missing await waitUntilExit() -- Command exits before Ink UI completes, user sees nothing
  • Using console.log in commands -- Breaks --json output mode and is not captured by @oclif/test
  • Bare strings in Ink -- All text must be wrapped in <Text> or rendering fails
  • Blocking the render loop -- Synchronous work in components freezes the terminal UI

Medium Priority:

  • .tsx files as commands -- oclif does not auto-discover .tsx files; use .ts command files that import .tsx components
  • Missing Ctrl+C handling -- Always provide an exit mechanism via useInput or useApp().exit()
  • No cleanup in useEffect -- Async operations must be canceled on unmount to avoid state updates after exit
  • Conflicting useInput hooks -- Multiple active useInput hooks fire simultaneously; use the isActive option to scope them

Gotchas & Edge Cases:

  • oclif hooks run in parallel, not sequence -- don't depend on execution order between hooks
  • useInput fires once for pasted text, not per-character -- handle multi-character input strings explicitly
  • Ink v5 requires React 18+, Ink v6 requires React 19+ -- check your Ink version's peer dependencies
  • enableJsonFlag makes run() return value the JSON output -- ensure the return type matches what consumers expect
  • oclif's this.error() throws (exits the process) -- it does not return

</red_flags>


<critical_reminders>

CRITICAL REMINDERS

(You MUST await waitUntilExit() after render() in oclif commands -- without it the process exits before the UI completes)

(You MUST use this.log() / this.warn() / this.error() in commands -- console.log breaks --json mode and test capture)

(You MUST wrap all text in <Text> components in Ink -- bare strings cause rendering errors)

(You MUST use useEffect cleanup to cancel async operations -- Ink components unmount when the user presses Ctrl+C)

Failure to follow these rules will cause silent process exits, broken JSON output, and terminal rendering crashes.

</critical_reminders>

Files (skills)
  • examples
    • advanced.md 17.6 KB
      Loading…
    • core.md 14.3 KB
      Loading…
    • testing.md 14.7 KB
      Loading…
  • SKILL.md 12 KB
    ---
    name: cli-framework-oclif-ink
    description: Modern CLI development combining oclif's command framework with Ink's React-based terminal rendering
    ---
    
    # oclif + Ink CLI Patterns
    
    > **Quick Guide:** Use oclif for command routing, flag/arg parsing, and plugin architecture. Use Ink for React-based interactive terminal UIs with Flexbox layout. Combine both when commands need rich stateful interfaces. Always `await waitUntilExit()` when rendering Ink from oclif commands. Use `this.log()` instead of `console.log` to preserve JSON output mode.
    
    ---
    
    <critical_requirements>
    
    ## CRITICAL: Before Using This Skill
    
    **(You MUST `await waitUntilExit()` after `render()` in oclif commands -- without it the process exits before the UI completes)**
    
    **(You MUST use `this.log()` / `this.warn()` / `this.error()` in commands -- `console.log` breaks `--json` mode and test capture)**
    
    **(You MUST wrap all text in `<Text>` components in Ink -- bare strings cause rendering errors)**
    
    **(You MUST use `useEffect` cleanup to cancel async operations -- Ink components unmount when the user presses Ctrl+C)**
    
    </critical_requirements>
    
    ---
    
    **Auto-detection:** oclif, @oclif/core, @oclif/test, Ink, ink, @inkjs/ui, Command class, Flags, Args, useInput, useApp, useFocus, render(), waitUntilExit, terminal UI, CLI command, ink-testing-library
    
    **When to use:**
    
    - Building multi-command CLIs with flag/arg parsing
    - Creating interactive terminal UIs (wizards, dashboards, progress displays)
    - Combining command routing with rich React-based interfaces
    - Building plugin-extensible CLI architectures
    
    **When NOT to use:**
    
    - Simple one-off scripts (plain Node.js suffices)
    - Basic prompts only (a lightweight prompt library suffices)
    - Performance-critical startup under 100ms (oclif adds ~200ms overhead)
    
    **Key patterns covered:**
    
    - oclif command structure with typed flags, args, and output methods
    - Ink components, Flexbox layout, keyboard input, and focus management
    - Integration: rendering Ink from oclif commands with lifecycle management
    - @inkjs/ui pre-built components (Select, TextInput, Spinner, etc.)
    - Plugin architecture and lifecycle hooks
    - Multi-step wizards, progress indicators, and cancelable operations
    - Testing commands with `@oclif/test` and components with `ink-testing-library`
    
    ---
    
    <philosophy>
    
    ## Philosophy
    
    oclif and Ink solve orthogonal problems. **oclif** handles the boring-but-critical parts: command routing, flag parsing, help generation, plugin discovery, auto-updates. **Ink** handles the interactive parts: stateful terminal UIs using React's component model with Flexbox layout.
    
    **Use oclif alone** when commands do their work and print output. **Add Ink** when a command needs real-time user interaction (wizards, dashboards, progress). The integration point is simple: the oclif command's `run()` calls `render()` and awaits `waitUntilExit()`.
    
    **Key architectural decisions:**
    
    - Commands are `.ts` files (not `.tsx`) -- they import Ink components from separate `.tsx` files
    - oclif handles process lifecycle; Ink handles UI lifecycle within it
    - Keyboard handling lives in Ink components via `useInput`, not in oclif commands
    - State management for complex Ink UIs should use an external store (not prop drilling)
    
    </philosophy>
    
    ---
    
    <patterns>
    
    ## Core Patterns
    
    ### Pattern 1: oclif Command with Typed Flags and Args
    
    Commands use static properties for metadata and flag/arg definitions. The `run()` method is async and returns typed data for JSON output support.
    
    ```typescript
    import { Command, Flags, Args } from "@oclif/core";
    
    const DEFAULT_RETRIES = 3;
    
    export class Deploy extends Command {
      static summary = "Deploy to target environment";
      static enableJsonFlag = true; // Adds --json flag
    
      static flags = {
        env: Flags.string({
          char: "e",
          required: true,
          options: ["staging", "production"] as const,
        }),
        retries: Flags.integer({
          char: "r",
          default: DEFAULT_RETRIES,
          min: 0,
          max: 10,
        }),
        verbose: Flags.boolean({ char: "v", default: false, allowNo: true }),
        apiKey: Flags.string({ env: "MY_CLI_API_KEY" }), // From env var
      };
    
      static args = {
        target: Args.string({ description: "Deploy target", required: true }),
      };
    
      async run(): Promise<{ status: string }> {
        const { args, flags } = await this.parse(Deploy);
        // Use this.log, this.warn, this.error -- never console.*
        this.log(`Deploying ${args.target} to ${flags.env}`);
        return { status: "deployed" };
      }
    }
    ```
    
    See [examples/core.md](examples/core.md) Pattern 1-5 for complete flag types, args, output methods, and error handling.
    
    ---
    
    ### Pattern 2: Ink Component with Keyboard Handling
    
    Ink components are React functional components using hooks for input, app lifecycle, and focus.
    
    ```tsx
    import React, { useState } from "react";
    import { Box, Text, useInput, useApp } from "ink";
    
    interface SelectorProps {
      items: string[];
      onSelect: (item: string) => void;
    }
    
    export const Selector: React.FC<SelectorProps> = ({ items, onSelect }) => {
      const [index, setIndex] = useState(0);
      const { exit } = useApp();
    
      useInput((input, key) => {
        if (key.upArrow) setIndex((i) => Math.max(0, i - 1));
        if (key.downArrow) setIndex((i) => Math.min(items.length - 1, i + 1));
        if (key.return) onSelect(items[index]);
        if (input === "q") exit();
      });
    
      return (
        <Box flexDirection="column">
          {items.map((item, i) => (
            <Text key={item} bold={i === index}>
              {i === index ? "> " : "  "}
              {item}
            </Text>
          ))}
        </Box>
      );
    };
    ```
    
    See [examples/core.md](examples/core.md) Pattern 6-8 for styling, layout, and @inkjs/ui components.
    
    ---
    
    ### Pattern 3: Rendering Ink from oclif Command
    
    The integration pattern: oclif command renders an Ink component and awaits its completion.
    
    ```typescript
    import { Command, Flags } from "@oclif/core";
    import { render } from "ink";
    import React from "react";
    import { SetupWizard } from "../components/setup-wizard.js";
    
    export class Init extends Command {
      static summary = "Initialize a new project";
      static flags = {
        yes: Flags.boolean({ char: "y", description: "Use defaults", default: false }),
      };
    
      async run(): Promise<void> {
        const { flags } = await this.parse(Init);
        if (flags.yes) {
          this.log("Initialized with defaults.");
          return;
        }
        // CRITICAL: Destructure waitUntilExit and await it
        const { waitUntilExit } = render(<SetupWizard />);
        await waitUntilExit();
      }
    }
    ```
    
    See [examples/core.md](examples/core.md) Pattern 9 for the full integration pattern with non-interactive fallback.
    
    ---
    
    ### Pattern 4: Multi-Step Wizard
    
    Wizards use step-based state with back/forward navigation and data accumulation.
    
    ```tsx
    const MultiStepWizard: React.FC<WizardProps> = ({ steps, onComplete }) => {
      const [currentIndex, setCurrentIndex] = useState(0);
      const [data, setData] = useState<Record<string, unknown>>({});
    
      const handleNext = (stepData: Record<string, unknown>) => {
        const merged = { ...data, ...stepData };
        setData(merged);
        if (currentIndex === steps.length - 1) onComplete(merged);
        else setCurrentIndex((i) => i + 1);
      };
    
      const handleBack = () => setCurrentIndex((i) => Math.max(0, i - 1));
      // Render steps[currentIndex].component with {onNext, onBack, data} props
    };
    ```
    
    See [examples/advanced.md](examples/advanced.md) Pattern 1-2 for complete wizard implementation with navigation.
    
    ---
    
    ### Pattern 5: Plugin Architecture
    
    oclif plugins are npm packages with their own commands and hooks. The host CLI registers plugins in package.json.
    
    ```json
    {
      "oclif": {
        "plugins": [
          "@oclif/plugin-help",
          "@oclif/plugin-autocomplete",
          "@myorg/cli-plugin-analytics"
        ]
      }
    }
    ```
    
    See [examples/advanced.md](examples/advanced.md) Pattern 4 for creating plugins and user-installable plugin support.
    
    ---
    
    ### Pattern 6: Testing Commands and Components
    
    Use `@oclif/test` for command tests (flags, args, output, errors) and `ink-testing-library` for Ink component tests (rendering, keyboard simulation).
    
    ```typescript
    // Command test
    import { runCommand } from "@oclif/test";
    const { stdout, error } = await runCommand(["deploy", "--env", "staging", "app"]);
    expect(stdout).toContain("Deploying");
    
    // Ink component test
    import { render } from "ink-testing-library";
    const { lastFrame, stdin } = render(<Selector items={["a", "b"]} onSelect={fn} />);
    stdin.write("\u001B[B"); // Down arrow
    stdin.write("\r");       // Enter
    expect(fn).toHaveBeenCalledWith("b");
    ```
    
    See [examples/testing.md](examples/testing.md) for full testing patterns including async operations, mocking, and snapshot tests.
    
    </patterns>
    
    ---
    
    <decision_framework>
    
    ## Decision Framework
    
    ```
    Building a CLI?
    |
    +-> Need multiple commands / subcommands?
    |   +-> YES -> oclif (multi-command mode)
    |   +-> NO  -> oclif (single-command mode) or plain Node.js
    |
    +-> Need interactive terminal UI?
    |   +-> Simple prompts (name, confirm)? -> Lightweight prompt library
    |   +-> Complex stateful UI (wizard, dashboard)? -> Ink
    |
    +-> Need both routing AND complex UI?
        +-> YES -> oclif commands + Ink components
        +-> NO  -> Use whichever fits the primary need
    ```
    
    ### Command File Organization
    
    ```
    src/
      commands/           # oclif command classes (.ts files)
        init.ts
        config/
          get.ts          # mycli config get <key>
          set.ts          # mycli config set <key> <value>
      components/         # Ink React components (.tsx files)
        wizard.tsx
        progress.tsx
      hooks/              # oclif lifecycle hooks
        init.ts           # Runs before every command
        postrun.ts        # Runs after every command
      lib/                # Shared utilities
    ```
    
    </decision_framework>
    
    ---
    
    **Detailed Resources:**
    
    - [examples/core.md](examples/core.md) -- Commands, flags, args, Ink components, integration
    - [examples/advanced.md](examples/advanced.md) -- Wizards, progress, plugins, hooks, error boundaries
    - [examples/testing.md](examples/testing.md) -- Command tests, component tests, async testing
    
    ---
    
    <red_flags>
    
    ## RED FLAGS
    
    **High Priority:**
    
    - **Missing `await waitUntilExit()`** -- Command exits before Ink UI completes, user sees nothing
    - **Using `console.log` in commands** -- Breaks `--json` output mode and is not captured by `@oclif/test`
    - **Bare strings in Ink** -- All text must be wrapped in `<Text>` or rendering fails
    - **Blocking the render loop** -- Synchronous work in components freezes the terminal UI
    
    **Medium Priority:**
    
    - **`.tsx` files as commands** -- oclif does not auto-discover `.tsx` files; use `.ts` command files that import `.tsx` components
    - **Missing Ctrl+C handling** -- Always provide an exit mechanism via `useInput` or `useApp().exit()`
    - **No cleanup in useEffect** -- Async operations must be canceled on unmount to avoid state updates after exit
    - **Conflicting `useInput` hooks** -- Multiple active `useInput` hooks fire simultaneously; use the `isActive` option to scope them
    
    **Gotchas & Edge Cases:**
    
    - oclif hooks run in **parallel**, not sequence -- don't depend on execution order between hooks
    - `useInput` fires **once** for pasted text, not per-character -- handle multi-character input strings explicitly
    - Ink v5 requires **React 18+**, Ink v6 requires **React 19+** -- check your Ink version's peer dependencies
    - `enableJsonFlag` makes `run()` return value the JSON output -- ensure the return type matches what consumers expect
    - oclif's `this.error()` throws (exits the process) -- it does not return
    
    </red_flags>
    
    ---
    
    <critical_reminders>
    
    ## CRITICAL REMINDERS
    
    **(You MUST `await waitUntilExit()` after `render()` in oclif commands -- without it the process exits before the UI completes)**
    
    **(You MUST use `this.log()` / `this.warn()` / `this.error()` in commands -- `console.log` breaks `--json` mode and test capture)**
    
    **(You MUST wrap all text in `<Text>` components in Ink -- bare strings cause rendering errors)**
    
    **(You MUST use `useEffect` cleanup to cancel async operations -- Ink components unmount when the user presses Ctrl+C)**
    
    **Failure to follow these rules will cause silent process exits, broken JSON output, and terminal rendering crashes.**
    
    </critical_reminders>
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.