Introduction

    maltty is an opinionated CLI framework for Node.js. It gives you typed commands, middleware pipelines, configuration loading, authentication, and terminal UI out of the box -- so you can focus on what your CLI does, not how it's wired together.

    Prerequisites

    • Node.js 24+ -- maltty targets the current LTS release
    • pnpm (recommended) -- any package manager works, but maltty tooling assumes pnpm
    • TypeScript -- maltty relies on Zod inference and module augmentation, so TypeScript is required

    Why maltty?

    • Convention over configuration -- sensible defaults for commands, config discovery, and project layout
    • End-to-end type safety -- Zod schemas for args and config, module augmentation for global types, typed context in every handler
    • Middleware pipelines -- composable onion model for auth, logging, timing, and any cross-cutting concern
    • Built-in auth -- OAuth PKCE, device code, env vars, file tokens, and interactive login with zero boilerplate
    • Terminal UI -- logger, spinner, prompts, colors, and formatters all on ctx

    Project structure

    A typical maltty project looks like this:

    my-cli/
├── src/
│   ├── index.ts          # CLI entrypoint
│   ├── config.ts         # Config schema + module augmentation
│   ├── commands/
│   │   ├── deploy.ts     # Command definition
│   │   └── status.ts     # Command definition
│   └── middleware/
│       └── require-auth.ts
├── maltty.config.ts        # Build configuration
├── package.json
└── tsconfig.json

    Commands live in src/commands/, middleware in src/middleware/, and the entrypoint ties them together with a single cli() call. The build configuration in maltty.config.ts controls how @maltty/cli bundles your project for distribution.

    Feature matrix

    FeatureDescription
    Typed commandsZod schemas for args with full inference
    Middleware pipelinesComposable onion model for cross-cutting concerns
    Config discoveryAutomatic file loading with Zod validation
    AuthenticationOAuth PKCE, device code, env vars, file tokens
    Terminal UILogger, spinner, prompts, colors, formatters
    HTTP clientTyped fetch wrapper with auth header injection
    IconsNerd Font glyphs with emoji fallback
    Build & compileESM bundling via tsdown, standalone binaries via Bun

    Sub-exports

    The maltty package exposes focused sub-exports so you only import what you need:

    ExportPurpose
    malttyCommands, middleware, context, module augmentation
    maltty/configdefineConfig and the config middleware
    maltty/authAuth middleware and credential strategies
    maltty/httpHTTP client middleware
    maltty/iconsNerd Font icon middleware with emoji fallback
    maltty/figuresUnicode figure set for terminal output
    maltty/reportStructured reporting output
    maltty/storeFile-backed JSON store (createStore)
    maltty/projectProject root and dot-dir path resolution
    maltty/formatStandalone terminal formatting helpers
    maltty/uiInk UI primitives for terminal interfaces
    maltty/storiesComponent stories and preview decorators
    maltty/testTest utilities for commands and middleware

    Packages

    PackageDescription
    malttyCommands, middleware, config, context, auth, HTTP, and icons
    @maltty/cliScaffolding, building, diagnostics, and code generation

    Next steps

    • Quick Start -- build and run a CLI in 5 minutes
    • Build a CLI -- the full guide to commands, middleware, config, and sub-exports
    • Lifecycle -- how a CLI invocation flows from argv to exit