Stricli CLI Framework

Stricli is Bloomberg's type-safe CLI framework for TypeScript. It focuses on strongly typed flags and positional arguments, explicit command routing, automatic help generation, and isolated command context.

Prefer current upstream APIs and terminology:

buildCommand({ func | loader, parameters, docs })
buildRouteMap({ routes, docs, aliases?, defaultCommand? })
buildApplication(rootCommandOrRouteMap, config)
run(app, inputs, context)
CommandContext for runtime context

Upstream Orientation

Stricli's official quick start is Node and npm oriented. Follow that by default, but keep install and execution guidance package-manager agnostic when helpful.

Install Packages

npm install @stricli/core              # required
npm install @stricli/auto-complete     # optional, bash completion support
# pnpm add / bun add also work

Generate a New App

Prefer the upstream generator when scaffolding from scratch:

npx @stricli/create-app@latest my-app
# pnpm dlx / bunx also work

Quick Start

Create a minimal single-command CLI.

1. Define a Command

import { buildCommand } from "@stricli/core";

interface GreetFlags {
    readonly shout?: boolean;
}

export const greetCommand = buildCommand({
    docs: {
        brief: "Print a greeting"
    },
    parameters: {
        flags: {
            shout: {
                kind: "boolean",
                brief: "Uppercase the greeting",
                optional: true
            }
        },
        positional: {
            kind: "tuple",
            parameters: [
                {
                    brief: "Name to greet",
                    parse: String,
                    placeholder: "name"
                }
            ]
        }
    },
    func(this, flags: GreetFlags, name: string) {
        const message = `Hello, ${name}!`;
        this.process.stdout.write(
            `${flags.shout ? message.toUpperCase() : message}\n`
        );
    }
});

2. Build the Application

import { buildApplication } from "@stricli/core";
import { version } from "../package.json";
import { greetCommand } from "./commands/greet";

export const app = buildApplication(greetCommand, {
    name: "my-cli",
    versionInfo: {
        currentVersion: version
    }
});

3. Run the CLI

import { run } from "@stricli/core";
import { app } from "./app";

await run(app, process.argv.slice(2), { process });

Core Concepts

buildCommand() creates a command from either an inline func or a lazy loader
buildRouteMap() organizes commands into nested subcommands
buildApplication() wraps a root command or route map with runtime configuration
run() executes the application with already-tokenized CLI input and a runtime context

See Commands, Routing, and Applications for current API details.

Parameter Types

Stricli supports four flag kinds and two positional modes:

Flags: parsed, enum, boolean, counter
Positionals: tuple, array

Variadic behavior is configured with variadic, not a separate flag kind.

See Parameters.

Recommended Workflow

Single-Command CLI

Define a command with buildCommand
Add typed flags and positional arguments in parameters
Wrap it with buildApplication(command, config)
Run with run(app, process.argv.slice(2), { process })

Multi-Command CLI

Define commands independently
Organize them with buildRouteMap
Add route aliases or a defaultCommand if needed
Wrap the root route map with buildApplication(routes, config)

Large CLIs

Prefer the lazy loader pattern for heavy commands:

import { buildCommand, numberParser } from "@stricli/core";

export const analyzeCommand = buildCommand({
    docs: {
        brief: "Analyze a report"
    },
    parameters: {
        flags: {
            depth: {
                kind: "parsed",
                parse: numberParser,
                brief: "Traversal depth",
                optional: true,
                default: "1"
            }
        }
    },
    loader: async () => import("./impl")
});

Context and Testing

Stricli command context is based on CommandContext
Command implementations receive runtime context through this
Extend CommandContext to inject custom services or shared state
Test either by calling run(app, inputs, context) or by importing the command implementation directly

See Context and Examples.

Auto-Complete

@stricli/auto-complete currently supports bash. The current public integration is based on:

the standalone install/uninstall flow via @stricli/auto-complete
built-in buildInstallCommand() / buildUninstallCommand() commands for your app

See Auto-Complete.

Important Upstream Guidance

Prefer strict: true in tsconfig.json; Stricli relies on TypeScript inference
--version is available only when versionInfo is configured on the application
--helpAll is built in and reveals hidden commands and flags
-h is reserved for help, -H for help-all, and -v for version when version info is enabled
Official upstream docs and generator are Node/npm oriented; mention pnpm and bun alternatives when useful, but keep npm examples first

Only use APIs documented in this skill and its reference files. Stricli is a niche library with a narrow public API surface — do not invent flag kinds, parsers, application config fields, or auto-complete features that are not shown here. If something is not documented, assume it does not exist.

Reference Documentation

Commands, Routing, and Applications - buildCommand, buildRouteMap, buildApplication, run, lazy loaders, route aliases, default commands
Parameters - current flag and positional parameter patterns
Parsers - built-in parsers, custom parsers, async parsing
Context - CommandContext, custom context, testing, exit-code handling
Auto-Complete - bash auto-complete with @stricli/auto-complete
Examples - updated examples for common Stricli patterns

stricli

Safety Notice

Copy this and send it to your AI assistant to learn