How DSH Commands Work

Commands are the user-facing surface

A command is what users trigger from the UI or CLI. Unlike tools (which the model calls autonomously), commands are explicitly invoked by humans. Understanding commands is the second step after writing your first plugin.

Register a command

The minimal registration:

ctx.commands.register('my-cmd', {
  description: 'Run my custom command',
  action: (args) => {
    return `Got: ${JSON.stringify(args)}`;
  },
});

Commands can have typed arguments, help text, and subcommands. The action callback receives parsed arguments and returns a result the UI can display.

Arguments and validation

ctx.commands.register('greet', {
  description: 'Say hello to someone',
  args: {
    name: { type: 'string', description: 'Person to greet' },
  },
  action: ({ name }) => `Hello, ${name}!`,
});

Argument validation happens before action runs. Bad input produces an error instead of calling your code.

Why this matters for quality

Well-designed commands are one of the signals our scoring engine checks: clear descriptions, sensible arguments, and helpful error messages. Plugins with poor command UX score lower on the docs dimension.