# Commands

A custom command is a [Commander.js](https://github.com/tj/commander.js) command. It is used to run multiple steps pipelines
that require user interactivity or custom options. Example: `mycommand.js` in a `cmds` directory in a registered feature directory:

```js
import select from '@inquirer/select';
import { execute } from "@agent-smith/core";

async function run(args, options) {
    const res = await execute("git", ["diff", "--stat"]);
    console.log(res);
}

const cmd = {
    name: "commit [args...]",
    description: "Commit cmd",
    options: [
        "all",
        ["--pkg <name>", "commit for a given package"],
        ["--msg <name>", "the first line commit message"],
        ["--instructions <prompt>", "additional optional instructions"]
    ],
    run: run
};

export { cmd };
```

The `cmd` export must be an object with `name`, `description`, `run`, and optionally `options`. The `name` defines the CLI command name. The `run` function receives `(args, options)` from Commander.js.

Options are either an array of Commander Option format (`["-f, --flag <value>", "description"]`) or a string for a predefined
options set. Predefined options sets:

- *all*: all options (display + io + inference + chat)
- *inference*: inference options (model, ctx, template, sampling params, backend)
- *display*: debug and verbose options
- *io*: input and output options

For imports from `@agent-smith/cli`, the package exports:

- `displayOptions` — `[-v, --verbose]`, `[-d, --debug]`
- `inferenceOptions` — model, ctx, template, sampling params, backend, mcp
- `ioOptions` — input/output modes (clipboard, markdown, etc.)
- `allOptions` — the union of all option sets
- `parseCommandArgs` — utility to parse Commander.js arguments

For shell execution and clipboard operations, import from `@agent-smith/core`:

```js
import { execute, writeToClipboard } from "@agent-smith/core";
```

Interactive patterns use `@inquirer/select` or `@inquirer/prompts`:

```js
import select from '@inquirer/select';

const answer = await select({
    message: 'Select an action',
    default: "commit",
    choices: [
        { name: 'Commit', value: 'commit' },
        { name: 'Cancel', value: 'cancel' },
    ],
});
```

<a href="javascript:openLink('/terminal_client/agents/overview')">Next: Agents</a>