Config Files

dreamcli discovers and loads configuration files from standard locations. Config values participate in the flag resolution chain.

Linking Flags to Config

import {  } from '@kjanat/dreamcli';

.(['us', 'eu', 'ap']).('deploy.region');

This resolves deploy.region from the config file using dot-notation. If CLI argv and env var don't provide a value, the config file is checked next.

Config never overrides a value that was explicitly provided earlier in the chain.
For the full precedence rules and examples, see CLI Semantics.

Enabling Config Discovery

import { ,  } from '@kjanat/dreamcli';

const  = ('deploy');

('mycli')
  .('mycli') // app name for file discovery
  .()
  .();

This searches standard locations for config files named .mycli.json, mycli.config.json, etc.

Search Paths

Config discovery is platform-aware:

1. --config <path> or --config=<path> (explicit override)
2. ./.mycli.json, ./mycli.config.json (project-local)
3. Unix: $XDG_CONFIG_HOME/mycli/config.json
4. Unix fallback: ~/.config/mycli/config.json
5. Windows: %APPDATA%\\mycli\\config.json
6. Windows fallback: %USERPROFILE%\\AppData\\Roaming\\mycli\\config.json

Custom Formats

JSON is built-in. Add YAML, TOML, or any other format via configFormat():

Bun built-ins

import { ,  } from '@kjanat/dreamcli';

('mycli')
  .('mycli')
  .(
    (['yaml', 'yml'], Bun.YAML.parse),
Cannot find name 'Bun'. Do you need to install type definitions for Bun? Try `npm i --save-dev @types/bun` and then add 'bun' to the types field in your tsconfig.
  )
  .((['toml'], Bun.TOML.parse))
Cannot find name 'Bun'. Do you need to install type definitions for Bun? Try `npm i --save-dev @types/bun` and then add 'bun' to the types field in your tsconfig.
  .();

npm packages

import { ,  } from '@kjanat/dreamcli';
import {  as  } from 'yaml';
import {  as  } from '@iarna/toml';

('mycli')
  .('mycli')
  .((['yaml', 'yml'], ))
  .((['toml'], ))
  .();

configFormat(exts, parser) creates a loader config from the extension list and parse function, and configLoader(loader) registers that loader with the CLI.

Each extension should only be registered once per chain — registering the same extension with different parsers causes duplicate loading.

The parsed value still has to be a plain object, so YAML scalars, arrays, null, or multi-document YAML that parses to an array will fail as CONFIG_PARSE_ERROR.

What's Next?

• Shell Completions — generate completion scripts
• Flags — full flag resolution chain
• CLI Semantics — exact precedence and masking behavior