superclix

⚡ Superclix — TypeScript CLI Framework

Superclix is a lightweight and modern framework for building interactive CLI interfaces in TypeScript. It combines dynamic autocomplete, command history, pagination, interactive selectors, and i18n — all without relying on heavy external dependencies.

🚀 Main Features

• 🧠 Dynamic Autocomplete (with inline ghost text or via Tab)
• 🔁 Command History (navigable with ↑ / ↓)
• 📜 Built-in Pagination (ctx.paginate)
• 🎯 Interactive Selectors (ctx.select)
• 🌍 Internationalization (i18n) (English / French)
• ⚙️ Modular Architecture: Command, Feature, CLI, Adapter
• 💥 Built-in Commands: help, exit
• 🔔 Non-TTY Mode for CI/CD environments

🧩 Installation

npm install superclix
# or
yarn add superclix

🧠 Minimal Example

Here’s a simple CLI example using autocomplete and pagination:

import { Command, createCLI } from "superclix";
import { AutocompleteFeature } from "superclix/dist/features/autocomplete";
import { PaginationFeature } from "superclix/dist/features/pagination";
import { createLogger } from "superloggix/dist/logger";

// Create a compatible logger
const logger = createLogger({ level: "info", prefix: "⚡" });

// Initialize CLI
const cli = createCLI({
  logger,
  prompt: "superclix> ",
  enableGhost: true,
});

// Enable features
cli.use(new AutocompleteFeature());
cli.use(new PaginationFeature());

// Example command
class EchoCommand extends Command {
  public readonly signature = "echo <text>";
  public readonly description = "Displays the provided text back to the user.";

  constructor() {
    super("echo");
  }

  public async execute(ctx) {
    ctx.logger.info(ctx.args.text || "(no text provided)");
  }

  public async getCompletions() {
    return { args: ["Hello", "World", "Superclix", "TypeScript"] };
  }
}

// Register and run
cli.register(new EchoCommand());
cli.run();

💡 Built-in Commands

Command	Description
help	Lists all available commands with pagination
exit	Gracefully exits the CLI session

⚙️ Core API

🔸 createCLI(options)

Creates a new CLI instance.

const cli = createCLI({
  logger,            // Required logger
  prompt: "mycli> ", // Displayed prompt
  enableGhost: true, // Enables inline ghost suggestions
});

🔸 class Command

Base class to extend when creating a custom command.

Key methods:

• execute(ctx) — main command logic
• getCompletions(ctx) — static autocompletion
• onAutocomplete(ctx, argIndex, currentValue) — dynamic autocompletion

🔸 CLIContext

Object provided to every command:

Property	Type	Description
args	Record<string, any>	Positional arguments
options	Record<string, any>	Options --key=value
logger	Logger	Injected logger
paginate(lines)	Function	Displays paginated output
select(options)	Function	Provides an interactive selector
exit()	Function	Gracefully exits the CLI

🧰 Local Development

Package organization is private, sorry.

🧱 Project Structure

src/
├── core/
│   ├── CLI.ts               # Main class
│   ├── Command.ts           # Base class for commands
│   ├── Feature.ts           # Base for features
│   ├── adapters/
│   │   ├── TTYAdapter.ts    # Interactive mode
│   │   └── NonTTYAdapter.ts # Non-interactive mode
│   └── Parser.ts            # Argument parser
├── features/
│   ├── autocomplete.ts
│   ├── pagination.ts
│   └── selector.ts
├── utils/
│   ├── i18n.ts
│   ├── colors.ts
│   └── types.ts
└── dev/
    └── index.ts             # Example playground

🧪 Example Commands

• echo <text> → repeats the given text
• logs [--level=info|debug|warn|error] → paginated logs
• select → interactive selector
• fruit <name> [--color|--origin] → dynamic autocompletion
• config <section> [--set|--get] → contextual sub-arguments

🌍 Localization

Available languages:

• 🇬🇧 English (default)
• 🇫🇷 French

Change the default locale:

import { setDefaultLocale } from "superclix/dist/utils/i18n";
setDefaultLocale("fr");

🧩 License

MIT © 2025 — Built with ⚡ by Matt'