Flags

Flags are the richest primitive in dreamcli. Each flag declaration configures parsing, type inference, resolution, help text, and shell completions.

Flag Types

String

.;

Number

.;

Boolean

.;

Enum

.;

Array

.;

Custom

.;

Array flags are the one optional flag kind that still resolve to a value when unset: if no CLI/env/config/prompt/default value is found, they fall back to an empty array [].

For the exact parser rules around repeated flags, short-flag stacking, -- separator handling, and --no-* spellings, see CLI Semantics.

Modifiers

Every flag type supports the same modifier chain:

import {  } from '@kjanat/dreamcli';


  .()
  // short alias: -r
  .('r')
  // help text
  .('Target region')
  // default value (narrows type)
  .('us')
  // must resolve or error
  .()
  // resolve from env var
  .('DEPLOY_REGION')
  // resolve from config file
  .('deploy.region')
  // interactive fallback
  .({ : 'input', : 'Region?' })
  // deprecation warning
  .('Use --target instead')
  // inherit in subcommands
  .();

Resolution Chain

Each flag resolves through an ordered pipeline. Every step is opt-in:

flowchart LR
    A[CLI argv] --> B[Environment variable]
    B --> C[Config file]
    C --> D[Interactive prompt]
    D --> E[Default value]

The first source that provides a value wins. Required flags that don't resolve produce a structured error before the action handler runs.

Example

import {  } from '@kjanat/dreamcli';


  .(['us', 'eu', 'ap'])
  .('DEPLOY_REGION')
  .('deploy.region')
  .({ : 'select', : 'Which region?' })
  .('us');

Resolution order:

1. --region eu on the command line
2. DEPLOY_REGION=eu in environment
3. deploy.region: "eu" in config file
4. Interactive select prompt (TTY only)
5. Default value "us"

Required vs Optional

Optional

.;

Defaulted

.;

Required

.;

Boolean

.;

Custom Parsing

import {  } from '@kjanat/dreamcli';

.(() => {
  const  = new (());
  if (. !== 'https:') {
    throw new ('URL must use HTTPS');
  }
  return ;
});

The parse function receives the raw string value and returns the parsed type. Thrown errors become validation errors with the flag name in context.

Propagation

Flags marked with .propagate() are inherited by all subcommands:

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

const  = ('start')
  .('verbose', .().('v').())
  .(({ ,  }) => {
    if (.) {
      .('Verbose mode enabled');
    }
  });

('mycli').(
  ('deploy')
    .('verbose', .().('v').())
    .(),
);

What's Next?

• Arguments — positional argument types
• Config Files — config file resolution
• Interactive Prompts — prompt integration
• CLI Semantics — exact parser and precedence rules