Getting started

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

Install

Install @oscli-dev/oscli with the package manager you already use.

npm install @oscli-dev/oscli

First CLI

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

src/cli.ts

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

const cli = createCLI((b) => ({
  title: "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.");
});

Grow the same flow

Add typed flags or machine-readable output without changing the basic shape of the CLI.

src/cli.ts

const cli = createCLI((b) => ({
  title: "project setup",
  json: true,
  flags: {
    env: b
      .flag()
      .string()
      .label("Environment")
      .choices(["dev", "staging", "prod"] as const)
      .default("dev"),
  },
  prompts: {
    project: b.text().label("Project").default("my-app"),
  },
}));

await cli.run(async () => {
  await cli.prompt.project();
  cli.setResult({
    env: cli.flags.env,
    project: cli.storage.project,
  });
});