Arguments

Positional arguments are declared with arg and appear after the command name.

Argument Types

String

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

const  = .();

declare const : {
  : <typeof >;
};
.;

Number

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

const  = .();

declare const : {
  : <typeof >;
};
.;

Custom

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

const  = .(() => new ());

declare const : {
  : <typeof >;
};
.;

Declaration

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

('deploy')
  .('target', .().('Deploy target'))
  .(
    'version',
    .().('Version tag').(),
  )
  .(({  }) => {
    type  = typeof ;
  });

Arguments are positional — order matters:

$ mycli deploy production v1.2.3
#              ^^^^^^^^^^ ^^^^^^
#              target     version

Required vs Optional

Arguments are required by default. Use .optional() to make them optional:

Required

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

const  = .();

declare const : {
  : <typeof >;
};
.;

Optional

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

const  = .().();

declare const : {
  : <typeof >;
};
.;

Variadic Arguments

The last argument can be variadic, collecting all remaining positional values:

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

('copy')
  .(
    'files',
    .().().('Files to copy'),
  )
  .(({  }) => {
    .;
  });

$ mycli copy a.txt b.txt c.txt
# args.files = ['a.txt', 'b.txt', 'c.txt']

Environment-Backed Arguments

Arguments can fall back to environment variables when the positional value is missing:

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

('auth')
  .(
    'token',
    
      .()
      .('API_TOKEN')
      .('Token from env'),
  )
  .(({  }) => {
    .;
  });

If API_TOKEN=secret and no CLI value is provided, args.token === 'secret'.

STDIN-Backed Arguments

Arguments can also read from piped stdin with .stdin():

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

('format')
  .(
    'data',
    .().().('Read from STDIN'),
  )
  .(({  }) => {
    .;
  });

When the CLI value is omitted, dreamcli resolves arguments in this order: CLI → stdin → env → default. With stdinData: 'hello' in tests or piped input at runtime, args.data === 'hello'.

Passing the literal sentinel - means “skip normal CLI resolution for this slot and read stdin instead”. Omitted positional input follows CLI → stdin → env → default, while - bypasses the CLI step and therefore resolves through stdin → env → default.

.stdin() Constraints

Only one argument per command may call .stdin(), and stdin-backed arguments cannot also be variadic. If stdin is absent, resolution falls through to env/default and then to required vs optional behavior, so use .optional() when missing piped input should resolve to undefined instead of a validation error.

What's Next?

• Flags — flag types and resolution chain
• Output — structured output channel