or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

arguments.mdcommands.mdindex.mdoptions.mdshell.md
tile.json

index.mddocs/

COA (Command-Option-Argument)

COA is a comprehensive command-line parser library for Node.js that provides a fluent, chainable API for defining commands, options, and arguments. It automatically generates help text, enables programmatic usage, supports shell completion, and includes advanced features like asynchronous command execution through promises, validation, and complex parsing of values.

Package Information

  • Package Name: coa
  • Package Type: npm
  • Language: JavaScript (with TypeScript definitions)
  • Installation: npm install coa

Core Imports

const COA = require('coa');
// Or destructured (note: Opt and Arg are undefined, use via classes)
const { Cmd, Opt, Arg, classes, shell, require } = require('coa');

ES6 modules:

import COA from 'coa';
// Or destructured (note: Opt and Arg are undefined, use via classes)
import { Cmd, Opt, Arg, classes, shell } from 'coa';

TypeScript:

import { Cmd, Opt, Arg, classes, shell } from 'coa';

Basic Usage

const COA = require('coa');

// Create a command-line program
COA.Cmd()
    .name(process.argv[1])
    .title('My awesome command line util')
    .helpful() // adds -h, --help
    .opt()
        .name('version')
        .title('Version')
        .short('v')
        .long('version')
        .flag()
        .act(function() {
            return '1.0.0';
        })
        .end()
    .cmd()
        .name('subcommand')
        .title('Example subcommand')
        .helpful()
        .arg()
            .name('input')
            .title('Input file')
            .req()
            .end()
        .act(function(opts, args) {
            console.log('Processing:', args.input);
        })
        .end()
    .run(process.argv.slice(2));

Architecture

COA is built around several key components:

  • Command Structure: Hierarchical command system with support for subcommands
  • Fluent API: Chainable method calls for building command definitions
  • Promise-based Execution: Asynchronous command execution using Q promises
  • Type System: Rich parameter types including arrays, boolean flags, required parameters
  • Validation Engine: Custom validation and type conversion functions
  • Shell Integration: Built-in bash completion and help text generation
  • Programmatic Usage: Commands can be used as modules via the API property

Capabilities

Command Definition and Execution

Core command functionality for creating command-line programs with subcommands, options, and arguments. Perfect for CLI tools and build systems.

function Cmd(cmd?: Cmd): Cmd;

interface Cmd {
  name(name: string): Cmd;
  title(title: string): Cmd;
  cmd(cmd?: Cmd): Cmd;
  opt(): Opt;
  arg(): Arg;
  act(act: ActionFunction, force?: boolean): Cmd;
  apply(fn: Function, args?: any[]): Cmd;
  comp(fn: CompletionFunction): Cmd;
  helpful(): Cmd;
  completable(): Cmd;
  extendable(pattern?: string): Cmd;
  usage(): string;
  run(argv: string[]): Cmd;
  do(argv: string[]): Promise<any>;
  invoke(cmds?: string|string[], opts?: any, args?: any): Promise<any>;
  reject(reason: any): Promise<never>;
  end(): Cmd;
  api(): any;
}

Command System

Option Configuration

Named parameters with short and long keys for command-line use. Supports flags, arrays, validation, and default values.

interface Opt {
  name(name: string): Opt;
  title(title: string): Opt;
  short(short: string): Opt;
  long(long: string): Opt;
  flag(): Opt;
  arr(): Opt;
  req(): Opt;
  only(): Opt;
  val(validation: ValidationFunction): Opt;
  def(def: any): Opt;
  input(): Opt;
  output(): Opt;
  act(act: ActionFunction): Opt;
  comp(fn: CompletionFunction): Opt;
  apply(...args: any[]): void;
  reject(...args: any[]): void;
  end(): Cmd;
}

Options

Argument Handling

Unnamed parameters from command-line arguments. Supports arrays, validation, and default values.

interface Arg {
  name(name: string): Arg;
  title(title: string): Arg;
  arr(): Arg;
  req(): Arg;
  val(validation: ValidationFunction): Arg;
  def(def: any): Arg;
  input(): Arg;
  output(): Arg;
  comp(fn: CompletionFunction): Arg;
  apply(...args: any[]): Arg;
  reject(...args: any[]): Arg;
  end(): Cmd;
}

Arguments

Shell Utilities

String escaping and unescaping utilities for shell command integration.

const shell: {
  escape(w: string): string;
  unescape(w: string): string;
};

Shell Utilities

Types

type ActionFunction = (opts: any, args: any[], res?: any) => any;
type ValidationFunction = (value: any) => boolean | any;
type CompletionFunction = (opts: any) => any;

interface Classes {
  Cmd: typeof Cmd;
  Opt: typeof Opt;
  Arg: typeof Arg;
}

// Main exports
declare const Cmd: (cmd?: Cmd) => Cmd;  // Factory function
declare const Opt: undefined;           // Not directly instantiable
declare const Arg: undefined;           // Not directly instantiable  
declare const classes: Classes;         // Class constructors
declare const shell: {                  // Shell utilities
  escape(w: string): string;
  unescape(w: string): string;
};
declare const require: NodeRequire;     // Node.js require function