@oscli-dev/oscli

TypeScript-first CLI framework for prompts, flags, and output.

Docs • npm • Examples

@oscli-dev/oscli lets you define prompts, flags, and output once, then reuse the same flow in interactive terminals, tests, and automation.

Install

Install the package with the package manager you already use.

npm install @oscli-dev/oscli
pnpm add @oscli-dev/oscli
yarn add @oscli-dev/oscli
bun add @oscli-dev/oscli

Quick start

Start with one flow, resolve prompts, and read typed values from cli.storage.

import { createCLI } from "@oscli-dev/oscli";

const cli = createCLI((b) => ({
  description: "project setup",
  prompts: {
    project: b.text().label("Project").default("my-app"),
    approved: b.confirm().label("Continue?").default(true),
  },
}));

await cli.run(async () => {
  cli.intro("project setup");

  await cli.prompt.project();
  await cli.prompt.approved();

  if (!cli.storage.approved) {
    cli.exit("Cancelled.", { code: "usage" });
  }

  cli.success(`Created ${cli.storage.project}`);
  cli.outro("Done.");
});

What you get

The core package covers the runtime pieces most CLIs need.

• Typed prompts and typed flags from one builder API.
• Interactive and non-interactive runs from the same flow.
• Built-in output helpers for tables, boxes, trees, diffs, spinners, and progress.
• Theme presets, JSON mode, and multi-command routing.
• cli.test() for deterministic tests without touching stdin.

Companion package

Use @oscli-dev/react when you want to embed an animated CLI demo in a React app or docs site.

Examples

The repository includes runnable examples for common workflows.

• create-app: project scaffolding
• deploy: flags, progress, and confirmations
• release: versioning and final summaries
• multi-command: subcommand routing

Docs

Use these pages next.

• Getting started
• Prompts
• Flags
• Testing
• Theme