or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

cli-management.md command-system.md help-system.md index.md option-system.md

tile.json

tessl/npm-cac

Simple yet powerful framework for building command-line apps

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:npm/cac@6.0.x

To install, run

npx @tessl/cli install tessl/npm-cac@6.0.0

CAC

CAC (Command And Conquer) is a lightweight, zero-dependency TypeScript/JavaScript library for building command-line interfaces and CLI applications. It provides a simple yet powerful API with just 4 main methods for basic CLI functionality, while supporting advanced features like git-style subcommands, variadic arguments, dot-nested options, negated options, default commands, and automatic help message generation.

Package Information

Package Name: cac
Package Type: npm
Language: TypeScript
Installation: npm install cac

Core Imports

import { cac } from "cac";
// Or import classes directly
import { cac, CAC, Command } from "cac";
// Default import
import cac from "cac";

For CommonJS:

const { cac } = require("cac");
// Default export
const cac = require("cac");
// Or directly call the factory function
const cli = require("cac")();
// Or destructure exports
const { cac, CAC, Command } = require("cac");

For Deno:

import { cac } from "https://unpkg.com/cac/mod.ts";

Basic Usage

import { cac } from "cac";

// Create CLI instance
const cli = cac("my-cli");

// Add global options
cli.option("--verbose", "Enable verbose output");

// Add commands
cli
  .command("build <entry>", "Build your app")
  .option("--minify", "Minify output")
  .action((entry, options) => {
    console.log(`Building ${entry}`);
    if (options.minify) console.log("Minifying...");
  });

// Enable help and version
cli.help();
cli.version("1.0.0");

// Parse arguments
cli.parse();

Architecture

CAC is built around several key components:

CLI Factory: The main cac() function creates CLI instances
CAC Class: Main CLI manager extending EventEmitter for command orchestration
Command System: Hierarchical command structure with global and command-specific options
Option Parser: Powerful option parsing with support for various patterns and types
Help System: Automatic help generation with customization callbacks
Argument Parsing: Support for required, optional, and variadic arguments

Capabilities

CLI Creation and Management

Core CLI instance creation and configuration. The foundation for building command-line applications.

/**
 * Create a CLI instance
 * @param name - Optional program name for help/version messages
 * @returns CAC instance
 */
function cac(name?: string): CAC;

/**
 * CAC class constructor - extends EventEmitter
 * @param name - Program name for help/version messages
 */
class CAC extends EventEmitter {
  constructor(name?: string);
}

CLI Management

Command Definition and Handling

Define commands with arguments, options, and actions. Supports subcommands, aliases, and flexible argument patterns.

/**
 * Add a command to the CLI
 * @param rawName - Command name with optional arguments like 'build <entry> [output]'
 * @param description - Command description
 * @param config - Optional command configuration
 * @returns Command instance for chaining
 */
command(rawName: string, description?: string, config?: CommandConfig): Command;

/**
 * Command class constructor
 * @param rawName - Raw command name with arguments
 * @param description - Command description
 * @param config - Command configuration
 * @param cli - Parent CLI instance
 */
class Command {
  constructor(rawName: string, description: string, config?: CommandConfig, cli?: CAC);
}

interface CommandConfig {
  allowUnknownOptions?: boolean;
  ignoreOptionDefaultValue?: boolean;
}

Command System

Option Parsing and Configuration

Define global and command-specific options with various types, defaults, and validation patterns.

/**
 * Add a global option
 * @param rawName - Option name(s) like '--output, -o <file>'
 * @param description - Option description
 * @param config - Optional configuration
 * @returns CLI instance for chaining
 */
option(rawName: string, description: string, config?: OptionConfig): CAC;

/**
 * Option class constructor
 * @param rawName - Raw option name with flags
 * @param description - Option description
 * @param config - Option configuration
 */
class Option {
  constructor(rawName: string, description: string, config?: OptionConfig);
}

interface OptionConfig {
  default?: any;
  type?: any[];
}

Option System

Help and Version Management

Automatic help generation with customization support and version display functionality.

/**
 * Enable help display on -h/--help
 * @param callback - Optional help customization callback
 * @returns CLI instance for chaining
 */
help(callback?: HelpCallback): CAC;

/**
 * Set version and enable version display on -v/--version
 * @param version - Version string
 * @param customFlags - Custom version flags (default: '-v, --version')
 * @returns CLI instance for chaining
 */
version(version: string, customFlags?: string): CAC;

type HelpCallback = (sections: HelpSection[]) => void | HelpSection[];

interface HelpSection {
  title?: string;
  body: string;
}

Help System

Core Types

interface ParsedArgv {
  args: ReadonlyArray<string>;
  options: { [k: string]: any };
}

interface CommandArg {
  required: boolean;
  value: string;
  variadic: boolean;
}

interface ParseOptions {
  /** Whether to run the matched command action (default: true) */
  run?: boolean;
}

type CommandExample = ((bin: string) => string) | string;

type ActionCallback = (
  ...args: Array<string | string[] | number | number[]>
) => any;

interface GlobalCommand extends Command {
  // Global command extending base Command class
}

Error Handling

class CACError extends Error {
  constructor(message: string);
}

CAC throws CACError instances for validation failures, unknown options, and missing required arguments. The library also supports event-based error handling through the EventEmitter interface.