Shell Completions

dreamcli generates completion scripts from the command schema — always in sync with your CLI definition.

Generating Scripts

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

const  = ('serve');
const  = ('mycli').();

(., 'bash');
(., 'zsh');
(., 'fish');
(., 'powershell');
(., 'bash', {
  : 'surface',
});

Supported Shells

Shell	Status
bash	Supported
zsh	Supported
fish	Supported
powershell	Supported

generateCompletion() currently supports bash, zsh, fish, and powershell.

The public Shell union and exported SHELLS tuple match this shipped set exactly.

See the Support Matrix for the current audited shell surface and the tracked follow-up work.

Adding a Completion Command

A common pattern is to add a completions subcommand:

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

const  = ('mycli');

const  = ('completions')
  .('Generate shell completion script')
  .(
    'shell',
    
      .(
        (): 'bash' | 'zsh' | 'fish' | 'powershell' => {
          if (
             !== 'bash' &&
             !== 'zsh' &&
             !== 'fish' &&
             !== 'powershell'
          ) {
            throw new (
              'Expected bash, zsh, fish, or powershell',
            );
          }
          return ;
        },
      )
      .('Target shell'),
  )
  .(({ ,  }) => {
    const  = (
      .,
      .,
    );
    .();
  });

.();

dreamcli also includes a built-in .completions() helper on cli():

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

const  = ('serve');
const  = ('status');

('mycli')
  .()
  .()
  .({ : 'surface' });

Users install completions by sourcing the output:

# bash
mycli completions bash >> ~/.bashrc

# zsh
mycli completions zsh >> ~/.zshrc

# fish
mycli completions fish > ~/.config/fish/completions/mycli.fish

# powershell
mycli completions powershell | Invoke-Expression

What Completes

Completion scripts generated from schema include:

• Command and subcommand names
• Flag names and aliases
• Enum flag values (choices)
• Argument descriptions

Root Completion Modes

When your CLI has a default command, root completion can expose different surfaces:

• 'subcommands' (default) keeps hybrid CLIs command-centric at the root
• 'surface' also exposes the default command's root-usable flags at the root

For a single visible default command, default mode still exposes that command's flags at the root.

Hidden defaults stay executable but are omitted from root completions. For the exact root-surface rules and examples, see CLI Semantics.

What's Next?

• Interactive Prompts — prompt integration
• Runtime Support — cross-runtime behavior
• CLI Semantics — exact root help and completion surface rules
• Support Matrix — current support truth