📦 Install

npm install @santana-org/cli
pnpm add @santana-org/cli

🚀 Quickstart

import { createCli } from "@santana-org/cli"
import { createLogger } from "@santana-org/logger"

const logger = createLogger({ label: "demo" })

const cli = createCli({
  name: "demo",
  version: "1.0.0",
  description: "A tiny CLI for the Santana Org ecosystem",
  branding: {
    title: "demo",
    tagline: "a small CLI with premium UX",
    badge: "developer tools",
  },
})
  .option("-v, --verbose", "enable verbose output")
  .command("greet", "print a greeting")
  .argument("<name>", "person to greet")
  .prompt("name", { message: "What is the name?" })
  .option("-l, --loud", "uppercase the output")
  .action(({ positionals, options }) => {
    const name = positionals.name as string
    logger.info(`hello, ${name}`)
  })

await cli.parse()

📖 API

createCli(options)

| Option | Type | Description | |---|---|---| | name | string | CLI binary name | | version | string | Version shown in --version | | description | string | Short description | | branding.title | string | Banner title | | branding.tagline | string | Banner subtitle | | branding.badge | string | Small label shown next to the title |

Chainable methods

| Method | Description | |---|---| | .option(flags, description) | Add a boolean or value flag | | .command(name, description) | Register a subcommand | | .argument(syntax, description) | Add a positional argument | | .prompt(key, { message }) | Ask for a missing text value at runtime | | .action(fn) | Handler receiving { positionals, options } | | .parse() | Parse process.argv and run |

✨ Interactive prompts

.prompt(...) makes a command interactive when the referenced value is missing from argv.

• Works with text values for now
• Uses a built-in terminal prompt by default
• If argv already provides the value, the prompt is skipped

Example:

const cli = createCli({ name: "demo" })
  .command("greet")
  .argument("<name>")
  .prompt("name", { message: "What is the name?", defaultValue: "Ada" })

🏗️ Design decisions

• Chainable API. Commands, flags, and arguments compose naturally in a single expression.
• Auto help. --help is generated automatically, styled with @santana-org/colors.
• Logger-friendly. Designed to pair with @santana-org/logger inside actions.
• Branding-first. First-class support for a recognizable CLI header out of the box.
• ESM-first. CJS interop included, written for modern runtimes.

📄 License

MIT © santana-org — contributions are welcome, see CONTRIBUTING.