# @kjanat/dreamcli

> Fully typed TypeScript CLIs with a lean install. Define once, infer everywhere.

Every documentation page is available as authored markdown under `/raw/`
(or send `Accept: text/markdown` to any page URL).

## Guide

- [Arguments](https://dreamcli.kjanat.dev/raw/guide/arguments): Positional arguments are declared with arg and appear after the command name.
- [Commands](https://dreamcli.kjanat.dev/raw/guide/commands): Commands are the primary building block in dreamcli.
- [Shell Completions](https://dreamcli.kjanat.dev/raw/guide/completions): dreamcli generates completion scripts from the command schema —
- [Config Files](https://dreamcli.kjanat.dev/raw/guide/config): dreamcli discovers and loads configuration files from standard locations.
- [Errors](https://dreamcli.kjanat.dev/raw/guide/errors): dreamcli provides structured errors with codes, suggestions, and JSON serialization.
- [Flags](https://dreamcli.kjanat.dev/raw/guide/flags): Flags are the richest primitive in dreamcli.
- [Getting Started](https://dreamcli.kjanat.dev/raw/guide/getting-started): npm install @kjanat/dreamcli
- [Help](https://dreamcli.kjanat.dev/raw/guide/help): Help text is generated from your schemas — usage line, arguments, flags,
- [Limitations And Workarounds](https://dreamcli.kjanat.dev/raw/guide/limitations): This page consolidates the most important current edges in DreamCLI's shipped surface.
- [Middleware](https://dreamcli.kjanat.dev/raw/guide/middleware): Middleware wraps downstream execution and can add typed context to the command handler chain.
- [Migration And Adoption](https://dreamcli.kjanat.dev/raw/guide/migration): This page is for serious evaluators and adopters deciding whether to move an existing CLI onto
- [Output](https://dreamcli.kjanat.dev/raw/guide/output): Handlers receive out instead of console.
- [Interactive Prompts](https://dreamcli.kjanat.dev/raw/guide/prompts): dreamcli integrates interactive prompts into the flag resolution chain.
- [Architecture Rationale](https://dreamcli.kjanat.dev/raw/guide/rationale): This page explains why dreamcli is shaped the way it is.
- [Standalone Flag Evaluation](https://dreamcli.kjanat.dev/raw/guide/read-flags): readFlags() takes a record of flag builders, evaluates it, and returns the
- [Runtime Support](https://dreamcli.kjanat.dev/raw/guide/runtime): dreamcli runs on Node.js, Bun, and Deno without code changes.
- [Schema Export](https://dreamcli.kjanat.dev/raw/guide/schema-export): dreamcli can export the complete CLI schema as JSON — for tooling,
- [CLI Semantics](https://dreamcli.kjanat.dev/raw/guide/semantics): This page is the canonical source of truth for dreamcli's edge-case behavior.
- [Testing](https://dreamcli.kjanat.dev/raw/guide/testing): dreamcli's test harness runs commands in-process with full control over inputs and outputs.
- [Troubleshooting](https://dreamcli.kjanat.dev/raw/guide/troubleshooting): This page covers the most likely real failure modes when building or evaluating a DreamCLI app.
- [Upgrading From 2.x To 3.0](https://dreamcli.kjanat.dev/raw/guide/upgrading-v3): This page covers moving an existing dreamcli 2.5.0 CLI to 3.0.0. For adopting
- [Upgrading From 3.x To 4.0](https://dreamcli.kjanat.dev/raw/guide/upgrading-v4): This page covers moving an existing dreamcli 3.x CLI to 4.0.0. Coming from 2.x,
- [Walkthrough: Building a GitHub CLI](https://dreamcli.kjanat.dev/raw/guide/walkthrough): Let's build something real.
- [Why dreamcli](https://dreamcli.kjanat.dev/raw/guide/why): Most TypeScript CLI frameworks treat the type system like decoration.

## Concepts

- [Anatomy of a CLI](https://dreamcli.kjanat.dev/raw/concepts/anatomy): You open a terminal. You type something. Something happens. That's a CLI.
- [Errors](https://dreamcli.kjanat.dev/raw/concepts/errors): Every CLI will eventually fail. The difference between a good CLI and a frustrating one is what
- [Exit Codes](https://dreamcli.kjanat.dev/raw/concepts/exit-codes): When a program finishes, it returns a number. That number is the exit code, and it's how a CLI
- [Input Sources](https://dreamcli.kjanat.dev/raw/concepts/input): A CLI gets its data from all over the place — flags you type, env vars, config files, piped input.
- [Output and TTY](https://dreamcli.kjanat.dev/raw/concepts/output): CLIs communicate through text.
- [Testing CLIs](https://dreamcli.kjanat.dev/raw/concepts/testing): Testing a CLI is harder than testing a library.

## Examples

- [Examples](https://dreamcli.kjanat.dev/raw/examples/index): DreamCLI's examples pages are generated at build time from the repo's real source examples via dynamic routes.

## Reference

- [API Reference](https://dreamcli.kjanat.dev/raw/reference/api): This page is rebuilt at docs build time from the public entrypoints declared in package.json.
- [Changelog](https://dreamcli.kjanat.dev/raw/reference/changelog): This page surfaces the repository changelog directly inside the docs site.
- [@kjanat/dreamcli/completion](https://dreamcli.kjanat.dev/raw/reference/completion): Shell completion script generation. cli().completions() loads this module on demand; import it
- [@kjanat/dreamcli/config](https://dreamcli.kjanat.dev/raw/reference/config): Config file and package manifest discovery. cli().run() loads discovery code on demand when
- [Example Hover](https://dreamcli.kjanat.dev/raw/reference/example-hover-prototype): DreamCLI now ships Twoslash-backed hover on generated example pages.
- [@kjanat/dreamcli/json-schema](https://dreamcli.kjanat.dev/raw/reference/json-schema): Definition documents and input JSON Schema generation. --help --json loads this module on demand;
- [@kjanat/dreamcli](https://dreamcli.kjanat.dev/raw/reference/main): The main export. Import schema builders, CLI runner, output, parsing, and errors.
- [Output Contract](https://dreamcli.kjanat.dev/raw/reference/output-contract): This page records the internal output-policy boundary for the dreamcli-re-foundation workstream.
- [Planner Contract](https://dreamcli.kjanat.dev/raw/reference/planner-contract): This page records the internal planner boundary for the dreamcli-re-foundation workstream.
- [@kjanat/dreamcli/prompt](https://dreamcli.kjanat.dev/raw/reference/prompt): Prompt engines. When stdin is a TTY and no prompter was injected, cli().run() installs a thin
- [Resolver Contract](https://dreamcli.kjanat.dev/raw/reference/resolver-contract): This page records the internal resolver boundary for the dreamcli-re-foundation workstream.
- [@kjanat/dreamcli/runtime](https://dreamcli.kjanat.dev/raw/reference/runtime): Runtime adapter factory and platform detection.
- [Schema](https://dreamcli.kjanat.dev/raw/reference/schema): @kjanat/dreamcli/schema is the package's published definition-schema export.\
- [Semantic Delta Log](https://dreamcli.kjanat.dev/raw/reference/semantic-delta-log): This page records which re-foundation changes preserved DreamCLI behavior versus which ones
- [Stability Policy](https://dreamcli.kjanat.dev/raw/reference/stability): This page classifies every exported type and value by the compatibility contract
- [Support Matrix](https://dreamcli.kjanat.dev/raw/reference/support-matrix): This page is the audited truth source for DreamCLI's current support surface.
- [@kjanat/dreamcli/testkit](https://dreamcli.kjanat.dev/raw/reference/testkit): Test utilities for running commands in-process.
- [@kjanat/dreamcli/version](https://dreamcli.kjanat.dev/raw/reference/version): DreamCLI's own build-time version constants. They identify the framework build for diagnostics,

## Other

- [docs — VitePress site + source-backed content](https://dreamcli.kjanat.dev/raw/AGENTS): Docs are half authored Markdown, half generated site/data pipeline. docs/.vitepress/ owns config,