@cloud-copilot/cli/dist/esm/cli.d.ts

A standardized library for CLI building TypeScript CLI applications

import { Argument } from './arguments/argument.js';
type ParsedArguments<T extends Record<string, Argument<any>>> = {
    [K in keyof T as K]: T[K] extends Argument<infer V> ? V : never;
};
/**
 * A subcommand that can be used in the CLI.
 */
export type Subcommand = {
    description: string;
    arguments: Record<string, Argument<any>>;
};
/**
 * A map of CLI argument keys to their configuration.
 */
export type Config<T extends Record<string, Argument<any>>> = T;
interface ConsoleLogger {
    log: (...args: any[]) => void;
}
/**
 * Additional arguments that can be used to configure the CLI parser.
 */
export interface AdditionalCliOptions {
    /**
     * The version of the CLI command. If provided, the CLI provides a --version flag that prints the version and exits.
     *
     * If a string is provided, it is printed as-is.
     * If an object it can have the following properties:
     * - currentVersion: the current version of the CLI. This can be a string or a function that returns a Promise<string> or string.
     * - checkForUpdates: Can be:
     *   - a string name of the npm package to check for updates
     *   - a function that returns a Promise<string | null> that returns the latest version or null if no update is available.
     * - updateMessage: a function that takes the current version and latest version and returns a string message to display when an update is available.
     */
    version?: string | {
        currentVersion: string | (() => Promise<string> | string);
        checkForUpdates?: string | (() => Promise<string | null>);
        updateMessage?: (current: string, latest: string) => string;
    };
    /**
     * The argument string from the CLI. If not provided, the process.argv.slice(2) is used.
     */
    args?: string[];
    /**
     * The environment variables to use for parsing. If not provided, process.env is used.
     */
    env?: Record<string, string>;
    /**
     * The prefix to use for environment variables. If provided, the CLI will look for environment variables with the prefix followed by an underscore.
     */
    envPrefix?: string;
    /**
     * The name of the operands to display in the help message. Defaults to "operands".
     */
    operandsName?: string;
    /**
     * Whether a subcommand is required. If true, the CLI will exit with an error if no subcommand is provided.
     */
    requireSubcommand?: boolean;
    /**
     * If there are zero arguments, show the help message. Defaults to false.
     */
    showHelpIfNoArgs?: boolean;
    /**
     * Expect operands. Whether the app expects operands. Defaults to true.
     *
     * Changes the help message to include operands.
     */
    expectOperands?: boolean;
    /**
     * Allow operands from standard input. If true, the help will include a note about reading operands from standard input.
     *
     * Defaults to false
     */
    allowOperandsFromStdin?: boolean;
    /**
     * A logger to use for printing help messages. If not provided, console.log is used.
     */
    consoleLogger?: ConsoleLogger;
}
type OperandsType<A extends AdditionalCliOptions> = A extends {
    expectOperands: false;
} ? never : string[];
export type SelectedSubcommandWithArgs<C extends Record<string, Subcommand>, O extends Record<string, Argument<any>>, A extends AdditionalCliOptions> = keyof C extends never ? {
    subcommand: never;
    args: ParsedArguments<O>;
    operands: OperandsType<A>;
    anyValues: boolean;
    printHelp: () => void;
} : A extends {
    requireSubcommand: true;
} ? {
    [K in keyof C]: {
        subcommand: K;
        args: ParsedArguments<C[K]['arguments']> & ParsedArguments<O>;
        operands: OperandsType<A>;
        anyValues: boolean;
        printHelp: () => void;
    };
}[keyof C] : {
    subcommand: undefined;
    args: ParsedArguments<O>;
    operands: OperandsType<A>;
    anyValues: boolean;
    printHelp: () => void;
} | {
    [K in keyof C]: {
        subcommand: K;
        args: ParsedArguments<C[K]['arguments']> & ParsedArguments<O>;
        operands: OperandsType<A>;
        anyValues: boolean;
        printHelp: () => void;
    };
}[keyof C];
type Only<A, B> = {
    [K in keyof A]: K extends keyof B ? A[K] : never;
} & Partial<B>;
/**
 * Parse CLI Arguments and return the parsed typesafe results.
 *
 * @param command the name of the command arguments are being parsed for.
 * @param subcommands the list of subcommands that can be used, if any.
 * @param cliArgs the configuration options for the CLI command.
 * @param additionalOptions additional arguments to be used for parsing and displaying help.
 * @returns the parsed arguments, operands, and subcommand if applicable.
 */
export declare function parseCliArguments<const O extends Record<string, Argument<any>>, const C extends Record<string, Subcommand>, const A extends AdditionalCliOptions>(command: string, subcommands: C, cliArgs: Config<O>, additionalOptions?: Only<A, AdditionalCliOptions>): Promise<SelectedSubcommandWithArgs<C, O, A>>;
export declare function printHelpContents<O extends Record<string, Argument<any>>, C extends Record<string, Subcommand>>(command: string, subcommands: C, cliOptions: O, additionalArgs?: AdditionalCliOptions, selectedSubcommand?: string | undefined): void;
export {};
//# sourceMappingURL=cli.d.ts.map