Examples

DreamCLI's examples pages are generated at build time from the repo's real source examples via dynamic routes.

• Source of truth: examples/*.ts
• Route loader: docs/examples/[slug].paths.ts
• Data loader: docs/examples/examples.data.ts
• Generated example source blocks use ts twoslash against local dreamcli source

Each example gets its own searchable page with usage snippets, hover-enabled source, and related API links. Hover stays scoped to the generated example source blocks; guide pages and shell transcripts remain plain docs. This keeps examples and API docs aligned to the same source model without maintaining separate docs mirrors.

Source-Backed Examples

• Basic single-command CLI. - typed positional args, typed flags, aliases, and default values. (examples/basic.ts)
• The v3 flag-type family in one command. - `flag.url()`, `flag.path()` with directory creation, `flag.date()`, `flag.duration()`, `flag.bytes()`, `flag.count()`, `flag.keyValue()`, string constraints, and array `.separator()`/`.unique()`. (examples/flag-types.ts)
• Help rendering configuration. - `.help()` theming, `flagOrder: 'declaration'`, a routable default command (`.default(cmd, { route: true })`), and footer control. (examples/help-config.ts)
• Interactive prompts with config file fallback. - per-flag `.prompt()`, `.env()`, `.config()`, and the full resolution chain (CLI → env → config → prompt → default). (examples/interactive.ts)
• Mixed machine-readable JSON and human-readable side-channel output. - machine-readable `out.json()` stdout, `out.status()` stderr side channels suppressible with `--quiet`, and `--json` for CLI-managed structured errors. (examples/json-mode.ts)
• Middleware patterns: auth guard, request timing, error handling. - typed middleware context, auth guards, short-circuiting, and wrap-around timing. (examples/middleware.ts)
• Multi-command CLI with nested command groups (git-like). - top-level commands, nested groups, version metadata, and env-backed flags. (examples/multi-command.ts)
• Output channel extras: colors, hyperlinks, and exit codes without throwing. - the gated `out.color` palette, OSC 8 hyperlinks behind `out.isHyperlinkSupported`, and `out.setExitCode()` for "report and continue" failures. (examples/output-extras.ts)
• Parser-level controls: negation, duplicate policy, and spelling parity. - `flag.boolean().negatable()` for `--no-<name>`, `.duplicates('error' | 'first' | 'last')` on singleton flags, and the built-in kebab ↔ camel spelling parity. (examples/parser-control.ts)
• Spinner and progress bar usage. - `out.spinner()`, `out.progress()`, `spinner.wrap()`, and automatic suppression in non-TTY or `--json` mode. (examples/spinner-progress.ts)
• Standard Schema validation for custom flags and args. - `flag.custom(schema)` accepting any Standard Schema v1 validator with inferred output types. Zod 4, Valibot, and ArkType all conform; the inline schema below shows the contract itself with zero dependencies. (examples/standard-schema.ts)
• Testing examples using @kjanat/dreamcli/testkit. - `runCommand()`, prompt answers, env/config injection, output assertions, middleware context, and activity assertions. (examples/testing.ts)
• Single-transport launcher (language-server style). - an "exactly one of" rule via `.derive()` throwing `CLIError`, declarative numeric constraints (`flag.number({ int: true, min: 1, max: 65535 })`), a kebab-case flag name accessed with bracket notation (`flags['node-ipc']`), and passing a typed result to the action through derived context. (examples/transport-launcher.ts)