@salesforce/command/lib/sfdxFlags.d.ts

Salesforce CLI base command class

/// <reference types="node" />
import { URL } from 'url';
import { Interfaces } from '@oclif/core';
import { Duration } from '@salesforce/kit';
import { Omit, Optional } from '@salesforce/ts-types';
import { CustomOptionFlag } from '@oclif/core/lib/interfaces/parser';
import { Deprecation } from './ux';
/**
 * @deprecated Use Flags from `@salesforce/sf-plugins-core` instead
 */
export declare namespace flags {
    type Any<T> = Omit<Partial<Interfaces.Flag<T>>, 'deprecated'> & SfdxProperties;
    type Array<T = string> = Option<T[]> & {
        delimiter?: string;
    };
    type BaseBoolean<T> = Partial<Interfaces.BooleanFlag<T>>;
    type Boolean<T = any> = BaseBoolean<T> & SfdxProperties;
    type Bounds<T> = {
        min?: T;
        max?: T;
    };
    type Builtin = {
        type: 'builtin';
    } & Partial<SfdxProperties>;
    type DateTime = Option<Date>;
    type Deprecatable = {
        deprecated?: Deprecation;
    };
    type Describable = {
        description: string;
        longDescription?: string;
    };
    type Discriminant = {
        kind: Kind;
    };
    type Discriminated<T> = T & Discriminant;
    type Enum<T> = Interfaces.EnumFlagOptions<T> & SfdxProperties;
    type Kind = keyof typeof flags;
    type Input<T extends Interfaces.FlagOutput> = Interfaces.FlagInput<T>;
    type MappedArray<T> = Omit<flags.Array<T>, 'options'> & {
        map: (val: string) => T;
        options?: T[];
    };
    type Milliseconds = Option<Duration> & Bounds<Duration | number>;
    type Minutes = Option<Duration> & Bounds<Duration | number>;
    type Number = Option<number> & NumericBounds;
    type NumericBounds = Bounds<number>;
    type Option<T = any> = Omit<Partial<CustomOptionFlag<T>>, 'deprecated'> & SfdxProperties & Validatable;
    type Output = Interfaces.FlagOutput;
    type Seconds = Option<Duration> & Bounds<Duration | number>;
    type SfdxProperties = Describable & Deprecatable;
    type String = Option<string>;
    type Url = Option<URL>;
    type Validatable = {
        validate?: string | RegExp | ((val: string) => boolean);
    };
}
declare function buildBoolean<T = boolean>(options: flags.Boolean<T>): flags.Discriminated<flags.Boolean<T>>;
declare function buildEnum<T>(options: flags.Enum<T>): flags.Discriminated<flags.Enum<T>>;
declare function buildHelp(options: flags.BaseBoolean<boolean>): flags.Discriminated<flags.Boolean<void>>;
declare function buildFilepath(options: flags.String): flags.Discriminated<flags.String>;
declare function buildDirectory(options: flags.String): flags.Discriminated<flags.String>;
declare function buildInteger(options: flags.Number): flags.Discriminated<flags.Number>;
declare function buildOption<T>(options: {
    parse: (val: string, ctx: unknown) => Promise<T>;
} & flags.Option<T>): flags.Discriminated<flags.Option<T>>;
declare function buildString(options: flags.String): flags.Discriminated<flags.String>;
declare function buildVersion(options?: flags.BaseBoolean<boolean>): flags.Discriminated<flags.Boolean<void>>;
declare function buildArray(options: flags.Array<string>): flags.Discriminated<flags.Array<string>>;
declare function buildArray<T>(options: flags.MappedArray<T>): flags.Discriminated<flags.Array<T>>;
declare function buildDate(options: flags.DateTime): flags.Discriminated<flags.DateTime>;
declare function buildDatetime(options: flags.DateTime): flags.Discriminated<flags.DateTime>;
declare function buildEmail(options: flags.String): flags.Discriminated<flags.String>;
declare function buildId(options: flags.String): flags.Discriminated<flags.String>;
declare function buildMilliseconds(options: flags.Milliseconds): flags.Discriminated<flags.Milliseconds>;
declare function buildMinutes(options: flags.Minutes): flags.Discriminated<flags.Minutes>;
declare function buildNumber(options: flags.Number): flags.Discriminated<flags.Number>;
declare function buildSeconds(options: flags.Seconds): flags.Discriminated<flags.Seconds>;
declare function buildUrl(options: flags.Url): flags.Discriminated<flags.Url>;
declare function buildBuiltin(options?: Partial<flags.Builtin>): flags.Builtin;
export declare const flags: {
    /**
     * A flag type whose presence indicates a `true` boolean value. Produces false when not present.
     */
    boolean: typeof buildBoolean;
    /**
     * A flag type with a fixed enumeration of possible option values. Produces a validated string from the `options` list.
     */
    enum: typeof buildEnum;
    /**
     * A flag type useful for overriding the short `char` trigger for emitting CLI help. Emits help and exits the CLI.
     */
    help: typeof buildHelp;
    /**
     * A flag type that accepts basic integer values. For floats, binary, octal, and hex, see {@link flags.number}.
     * Produces an integer `number`.
     */
    integer: typeof buildInteger;
    /**
     * A flag type for custom string processing. Accepts a `parse` function that converts a `string` value to a type `T`.
     * Produces a type `T`.
     */
    option: typeof buildOption;
    /**
     * A flag type for returning a raw `string` value without further preprocessing. Produces a string.
     */
    string: typeof buildString;
    /**
     * A flag type for emitting CLI version information. Emits the CLI version and exits the CLI.
     */
    version: typeof buildVersion;
    /**
     * A flag type for valid file paths. Produces a validated string.
     *
     * **See** [@salesforce/core#sfdc.validatePathDoesNotContainInvalidChars](https://forcedotcom.github.io/sfdx-core/globals.html#sfdc), e.g. "this/is/my/path".
     */
    filepath: typeof buildFilepath;
    /**
     * A flag type for valid directory paths. Produces a validated string.
     *
     * **See** [@salesforce/core#sfdc.validatePathDoesNotContainInvalidChars](https://forcedotcom.github.io/sfdx-core/globals.html#sfdc), e.g. "this/is/my/path".
     */
    directory: typeof buildDirectory;
    /**
     * A flag type for a delimited list of strings with the delimiter defaulting to `,`, e.g., "one,two,three". Accepts
     * an optional `delimiter` `string` and/or a custom `map` function for converting parsed `string` values into
     * a type `T`. Produces a parsed (and possibly mapped) array of type `T` where `T` defaults to `string` if no
     * custom `map` function was provided.
     */
    array: typeof buildArray;
    /**
     * A flag type for a valid date, e.g., "01-02-2000" or "01/02/2000 01:02:34". Produces a parsed `Date`.
     */
    date: typeof buildDate;
    /**
     * A flag type for a valid datetime, e.g., "01-02-2000" or "01/02/2000 01:02:34". Produces a parsed `Date`.
     */
    datetime: typeof buildDatetime;
    /**
     * A flag type for valid email addresses. Produces a validated string.
     *
     * **See** [@salesforce/core#sfdc.validateEmail](https://forcedotcom.github.io/sfdx-core/globals.html#sfdc), e.g., "me@my.org".
     */
    email: typeof buildEmail;
    /**
     * A flag type for valid Salesforce IDs. Produces a validated string.
     *
     * **See** [@salesforce/core#sfdc.validateSalesforceId](https://forcedotcom.github.io/sfdx-core/globals.html#sfdc), e.g., "00Dxxxxxxxxxxxx".
     */
    id: typeof buildId;
    /**
     * A flag type for a valid `Duration` in milliseconds, e.g., "5000".
     */
    milliseconds: typeof buildMilliseconds;
    /**
     * A flag type for a valid `Duration` in minutes, e.g., "2".
     */
    minutes: typeof buildMinutes;
    /**
     * A flag type for valid integer or floating point number, e.g., "42". Additionally supports binary, octal, and hex
     * notation. Produces a parsed `number`.
     */
    number: typeof buildNumber;
    /**
     * A flag type for a valid `Duration` in seconds, e.g., "5".
     */
    seconds: typeof buildSeconds;
    /**
     * A flag type for a valid url, e.g., "http://www.salesforce.com". Produces a parsed `URL` instance.
     */
    url: typeof buildUrl;
    /**
     * Declares a flag definition to be one of the builtin types, for automatic configuration.
     */
    builtin: typeof buildBuiltin;
};
export declare const requiredBuiltinFlags: {
    json(): flags.Discriminated<flags.Boolean<boolean>>;
    loglevel(): flags.Discriminated<flags.Enum<string>>;
};
export declare const optionalBuiltinFlags: {
    apiversion(opts?: flags.Builtin): flags.Discriminated<flags.String>;
    concise(opts?: flags.Builtin): flags.Discriminated<flags.Boolean<boolean>>;
    quiet(opts?: flags.Builtin): flags.Discriminated<flags.Boolean<boolean>>;
    targetdevhubusername(opts?: flags.Builtin): flags.Discriminated<flags.String>;
    targetusername(opts?: flags.Builtin): flags.Discriminated<flags.String>;
    verbose(opts?: flags.Builtin): flags.Discriminated<flags.Boolean<boolean>>;
};
/**
 * The configuration of flags for an {@link SfdxCommand} class, except for the following:
 *
 * * `json` and `loglevel` are configured automatically for all {@link SfdxCommand} classes.
 * * `targetusername` is enabled using either `SfdxCommand.supportsUsername` or `SfdxCommand.requiresUsername`.
 * * `targetdevhubusername` is enabled using either `SfdxCommand.supportsDevhubUsername` or `SfdxCommand.requiresDevhubUsername`.
 *
 * Additionally, `apiversion` is enabled automatically if any of the static `*Username` booleans are set, but may be
 * configured here explicitly as well if those settings are not required.
 *
 * ```
 * public static flagsConfig: FlagsConfig = {
 *   name: flags.string({ char: 'n', required: true, description: 'name of the resource to create' }),
 *   wait: flags.minutes({ description: 'number of minutes to wait for creation' }),
 *   notify: flags.url({ description: 'url to notify upon completion' })
 * };
 * ```
 */
export type FlagsConfig = {
    [key: string]: Optional<flags.Boolean | flags.Option | flags.Builtin>;
    /**
     * Adds the `apiversion` built-in flag to allow for overriding the API
     * version when executing the command.
     */
    apiversion?: flags.Builtin;
    /**
     * Adds the `concise` built-in flag to allow a command to support concise output,
     * which is useful when the output can be overly verbose, such as test results.
     * Note that this must be implemented by the command.
     */
    concise?: flags.Builtin;
    /**
     * Adds the `quiet` built-in flag to allow a command to completely suppress output.
     * Note that this must be implemented by the command.
     */
    quiet?: flags.Builtin;
    /**
     * Adds the `verbose` built-in flag to allow a command to support verbose output,
     * which is useful to display additional command results.
     * Note that this must be implemented by the command.
     */
    verbose?: flags.Builtin;
    targetdevhubusername?: never;
    targetusername?: never;
};
/**
 * Builds flags for a command given a configuration object.  Supports the following use cases:
 * 1. Enabling common SFDX flags. E.g., { verbose: true }
 * 2. Defining typed flags. E.g., { myFlag: Flags.array({ char: '-a' }) }
 * 3. Defining custom typed flags. E.g., { myFlag: Flags.custom({ parse: (val) => parseInt(val, 10) }) }
 *
 * @param {FlagsConfig} flagsConfig The configuration object for a flag.  @see {@link FlagsConfig}
 * @param options Extra configuration options.
 * @returns {flags.Output} The flags for the command.
 * @ignore
 */
export declare function buildSfdxFlags(flagsConfig: FlagsConfig, options: {
    targetdevhubusername?: boolean;
    targetusername?: boolean;
}): flags.Output;
export {};