API Reference#

@sigx/cli exposes four entry points:

• @sigx/cli — definePlugin, a (the @sigx/args builder), and the plugin types.
• @sigx/cli/plugin — the same plugin API surface (preferred for plugin authors).
• @sigx/cli/create — runCreate, the create command entry point.
• @sigx/cli/shell — runShell and the TUI shell runtime (documented in The shell runtime).

For the command-line surface (sigx create, sigx info, and plugin-provided commands), see Commands.

Functions#

definePlugin#

export function definePlugin(plugin: SigxPlugin): SigxPlugin;

Identity helper for authoring a sigx CLI plugin with type safety. It returns the plugin object unchanged, but checks it against the SigxPlugin contract. Import it from @sigx/cli/plugin (also re-exported from @sigx/cli).

• plugin — the plugin definition to validate and return.
• Returns — the same SigxPlugin object, unchanged.

As an alternative, you can use the satisfies SigxPlugin pattern instead of calling definePlugin.

defineCommand#

export function defineCommand<S extends ArgsShape = ArgsShape>(
    cmd: PluginCommand<S>,
): PluginCommand<S>;

Identity helper for authoring a single command outside a definePlugin literal — factoring a command into its own module or variable — while keeping run's ctx.args inferred from the command's args builders. Inside a definePlugin literal each command already infers per key, so defineCommand is only needed when a command is defined on its own. Import it from @sigx/cli/plugin (also re-exported from @sigx/cli).

a#

export const a; // the @sigx/args builder factory

Re-exported from @sigx/args. Use it to declare a command's arguments — a.string(), a.number(), a.boolean(), a.enum([...]), a.positional(), a.rest(), refined with .alias(), .default(), .required(), .multiple(), .describe(). See Authoring Plugins and the @sigx/args guide. The companion types AnyArg, ArgsShape, and InferArgs are exported alongside it.

runCreate#

export function runCreate(opts?: CreateOptions): Promise<void>;

Entry point of the create command, exported from @sigx/cli/create. The sigx binary calls it with the options it already parsed via @sigx/args; the bare @sigx/create shim (npm create @sigx@latest) calls it with no argument, in which case it parses process.argv itself. In a TTY it runs the interactive @sigx/terminal prompts; in non-interactive mode — no TTY, yes: true, or both type and a positional name — it scaffolds headlessly and calls process.exit() with the result code.

• opts — optional pre-parsed CreateOptions (name?, type?, styling?, yes?). Omitted, it reads process.argv.
• Returns — Promise<void> (the function exits the process when it finishes).

When the bare @sigx/create shim parses process.argv itself, it is lenient: unknown flags are tolerated (ignored rather than erroring), so a future sigx create flag never breaks an older shim. The one hard error is a trailing value-expecting flag with no value (e.g. a dangling --type), which exits with code 2.

Interfaces#

SigxPlugin#

export interface SigxPlugin {
    /** Unique plugin name (e.g. 'ssg', 'lynx') */
    name: string;
    /** Return true if this plugin handles the current project */
    detect: (cwd: string) => boolean;
    /** Commands this plugin provides */
    commands: Record<string, PluginCommand>;
    /** Optional TUI contributions merged into any plugin-hosted shell. */
    tui?: TuiContribution;
}

The plugin contract. A plugin package default-exports one of these (created via definePlugin or satisfies SigxPlugin).

• name — unique plugin name.
• detect — called during discovery with the current working directory; its commands are registered only when it returns true.
• commands — a map of command name to PluginCommand.
• tui — optional TUI contribution (tabs, slash commands, shortcuts, status items) merged into whichever plugin hosts the shell.

PluginCommand#

export interface PluginCommand<S = ArgsShape> {
    description: string;
    /** Fluent @sigx/args builders, e.g. `{ port: a.number().default(8788) }`. */
    args?: S;
    /** Alternate command names. Collisions warn; direct names beat aliases. */
    aliases?: string[];
    /** Hide from `sigx --help` (still dispatchable). */
    hidden?: boolean;
    /** Collect unknown flags into ctx.unknownFlags instead of erroring. */
    allowUnknownFlags?: boolean;
    run: (ctx: TypedCommandContext<S>) => Promise<void>;
}

Describes a single CLI command contributed by a plugin. It is generic over its args shape S, so run's ctx.args is inferred from the builders you declare — no cast.

• description — help text for the command.
• args — optional map of argument names to @sigx/args builders (a.*). See Declaring command arguments. Defaults to ArgsShape (Record<string, AnyArg>).
• aliases — alternate names the command also answers to. A collision with another command warns; a direct command name always beats an alias.
• hidden — omit the command from sigx --help while keeping it dispatchable.
• allowUnknownFlags — collect undeclared flags into ctx.unknownFlags instead of erroring on them.
• run — async handler receiving a TypedCommandContext<S>; resolves when the command finishes.

CommandContext#

export interface CommandContext {
    cwd: string;
    args: Record<string, unknown>;
    logger: Logger;
    plugins?: SigxPlugin[];
    cliVersion?: string;
    /** Unknown flag tokens — only when the command sets allowUnknownFlags. */
    unknownFlags?: string[];
}

The base context passed to a PluginCommand.run handler (see TypedCommandContext for the args-narrowed form your handler actually receives).

• cwd — process.cwd().
• args — the parsed arguments. args._ holds the verbatim tokens after a bare --.
• logger — a prefixed Logger.
• plugins — every plugin discovered for this project, so a shell-hosting command can merge peer plugins' TUI contributions via runShell({ plugins }).
• cliVersion — the running sigx binary's version, for plugin feature detection.
• unknownFlags — undeclared flag tokens, present only when the command sets allowUnknownFlags.

TypedCommandContext#

export type TypedCommandContext<S = ArgsShape> = Omit<CommandContext, 'args'> & {
    args: PluginArgs<S>;
};

export type PluginArgs<S> =
    ArgsShape extends S ? Record<string, unknown>
    : S extends ArgsShape ? InferArgs<S>
    : Record<string, unknown>;

CommandContext with args narrowed to the command's inferred shape. It's an intersection (not a generic member) so it stays assignable to CommandContext — a helper typed against CommandContext still accepts a TypedCommandContext. PluginArgs<S> resolves to the exact InferArgs<S> when S is a builders shape, and falls back to the legacy Record<string, unknown> for arg-less commands or hand-annotated contexts.

Logger#

export interface Logger {
    log: (msg: string) => void;
    warn: (msg: string) => void;
    error: (msg: string) => void;
}

Minimal logging interface available on CommandContext.logger. The core implementation prefixes messages with [sigx] and uppercases WARN / ERROR output.

• log — print an informational message.
• warn — print a warning.
• error — print an error.

Only log, warn, and error exist — there is no info method.

Shell runtime#

The @sigx/cli/shell entry point exports runShell, createShellLogger, collectTuiContributions, and mergeShellConfig, along with the ShellConfig, ShellHandle, TuiContribution, ShellTab, SlashCommand, Shortcut, and StatusItem types. These are documented in full in The shell runtime.