Commands

Commands are the primary building block in dreamcli. Every CLI has at least one.

Single Command

The simplest CLI is a single command wrapped in cli():

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

const  = ('greet')
  .('Greet someone')
  .('name', .().('Who to greet'))
  .('loud', .().('l'))
  .(({ , ,  }) => {
    const  = `Hello, ${.}!`;
    .(. ? .() : );
  });

('greet').().();

Multi-Command CLI

Use cli() to compose multiple commands:

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

const  = ('deploy')
  .('Deploy the app')
  .(({  }) => .('deploying...'));

const  = ('login')
  .('Authenticate')
  .(({  }) => .('logging in...'));

('mycli')
  .('1.0.0')
  .('My tool')
  .()
  .()
  .();

Command Groups

Nest commands under a group for cli group subcommand patterns:

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

const  = ('migrate')
  .('Run migrations')
  .(({  }) => .('migrating'));

const  = ('seed')
  .('Seed database')
  .(({  }) => .('seeding'));

const  = ('db')
  .('Database operations')
  .()
  .();

// Usage: mycli db migrate, mycli db seed

Groups can be nested arbitrarily deep.

Command Configuration

Description and Examples

import {  } from '@kjanat/dreamcli';

('deploy')
  .('Deploy to an environment')
  .('deploy production', 'Deploy to prod')
  .(
    'deploy staging --force',
    'Force deploy to staging',
  );

Default Command

Set a default command that runs when no subcommand is specified:

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

const  = ('main');
const  = ('other');

('mycli').().().();

Root behavior depends on what else is visible:

• a single visible default command merges its command help into root help
• visible sibling commands keep root help command-centric
• hidden defaults remain executable but are omitted from root help and root completions

For the exact root, help, and completion rules, see CLI Semantics.

Version

import {  } from '@kjanat/dreamcli';

('mycli').('1.0.0').();

Adds --version / -V automatically.

Action Handler

The .action() callback receives a single object with typed fields:

import {  } from '@kjanat/dreamcli';

('deploy').(
  ({ , , , ,  }) => {
		// args  — typed positional arguments
		// flags — typed flag values (fully resolved)
		// ctx   — typed middleware context
		// meta  — CLI metadata: name (program name), bin (invoked binary name),
		//         version (program version), command (leaf command name)
		// out   — output channel
	},
);

Actions can be async:

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

declare const : (
  : string,
  : <<string, unknown>>,
) => <unknown>;

('deploy')
  .('target', .())
  .(async ({ , ,  }) => {
    const  = await (., );
    .();
  });

What's Next?

• Related examples: Basic CLI, Multi-command CLI
• Flags — all flag types and modifiers
• Arguments — positional argument types
• Middleware — typed context propagation
• CLI Semantics — exact root and resolution behavior