0
# Command Definition
1

2
System for defining commands with usage patterns, descriptions, argument handling, and command aliases.
3

4
## Capabilities
5

6
### Command Method
7

8
Define a new command with usage pattern, description, and configuration options.
9

10
```javascript { .api }
11
/**
12
 * Define a new command with usage pattern and options
13
 * @param {string} usage - Command usage pattern with arguments
14
 * @param {string} [desc] - Command description  
15
 * @param {object} [opts] - Options including alias and default
16
 * @returns {Sade} Chainable instance
17
 */
18
command(usage, desc, opts);
19

20
interface CommandOptions {
21
  /** Alias names for the command */
22
  alias?: string | string[];
23
  /** Make this the default command */
24
  default?: boolean;
25
}
26
```
27

28
**Parameters:**
29

30
- `usage` (string, required): Command usage pattern with arguments
31
  - Required arguments: `<arg>` (throws error if missing)
32
  - Optional arguments: `[arg]` (undefined if not provided)
33
  - Multiple arguments: `<files..>` or `[options..]`
34
- `desc` (string, optional): Command description text
35
- `opts` (object, optional): Configuration options
36

37
**Usage Examples:**
38

39
```javascript
40
// Basic command
41
prog.command('build <src> <dest>')
42
  .describe('Build the source to destination')
43
  .action((src, dest, opts) => {
44
    console.log(`Building ${src} to ${dest}`);
45
  });
46

47
// Command with optional arguments
48
prog.command('serve [dir] [port]')
49
  .describe('Start development server')
50
  .action((dir = '.', port = 3000, opts) => {
51
    console.log(`Serving ${dir} on port ${port}`);
52
  });
53

54
// Command with aliases and default
55
prog.command('install [package]', 'Install a package', {
56
  alias: ['i', 'add'],
57
  default: true
58
});
59
```
60

61
### Describe Method
62

63
Add or update the description for the current command.
64

65
```javascript { .api }
66
/**
67
 * Add description to current command
68
 * @param {string|string[]} text - Description text or array of sentences
69
 * @returns {Sade} Chainable instance
70
 */
71
describe(text);
72
```
73

74
**Parameters:**
75

76
- `text` (string|string[], required): Description text
77
  - String: Automatically split into sentences
78
  - Array: Each item treated as a separate sentence
79
  - First sentence appears in general help, all sentences in command-specific help
80

81
**Usage Examples:**
82

83
```javascript
84
// Single line description
85
prog.command('test')
86
  .describe('Run the test suite');
87

88
// Multi-sentence description
89
prog.command('deploy')
90
  .describe([
91
    'Deploy application to production environment.',
92
    'This will build the app and upload it to the configured server.',
93
    'Make sure all tests pass before deploying.'
94
  ]);
95

96
// Automatic sentence splitting
97
prog.command('lint')
98
  .describe('Run linting checks. This will check code style and report issues.');
99
```
100

101
### Alias Method
102

103
Define one or more aliases (alternative names) for the current command.
104

105
```javascript { .api }
106
/**
107
 * Define aliases for current command
108
 * @param {...string} names - Alias names
109
 * @returns {Sade} Chainable instance
110
 * @throws {Error} If in single mode or no current command
111
 */
112
alias(...names);
113
```
114

115
**Parameters:**
116

117
- `...names` (string): One or more alias names for the current command
118

119
**Limitations:**
120
- Cannot be used in single-command mode
121
- Must be called after defining a command
122
- Does not check for conflicts with existing commands or aliases
123

124
**Usage Examples:**
125

126
```javascript
127
// Single alias
128
prog.command('install [package]')
129
  .alias('i');
130

131
// Multiple aliases
132
prog.command('install [package]')
133
  .alias('i', 'add', 'get');
134

135
// Chaining aliases
136
prog.command('install [package]')
137
  .alias('i')
138
  .alias('add', 'get');
139

140
// Via command options (equivalent to above)
141
prog.command('install [package]', 'Install a package', {
142
  alias: ['i', 'add', 'get']
143
});
144
```
145

146
**Help Output Example:**
147
```
148
  Description
149
    Install a package
150

151
  Usage
152
    $ npm install [package] [options]
153

154
  Aliases
155
    $ npm i
156
    $ npm add  
157
    $ npm get
158

159
  Options
160
    -h, --help    Displays this message
161
```
162

163
### Subcommands
164

165
Define hierarchical commands (subcommands) by including the full command path in the usage pattern.
166

167
**Usage Examples:**
168

169
```javascript
170
// Git-like subcommands
171
prog.command('remote add <name> <url>')
172
  .describe('Add a new remote repository')
173
  .action((name, url, opts) => {
174
    console.log(`Adding remote ${name}: ${url}`);
175
  });
176

177
prog.command('remote remove <name>')
178
  .describe('Remove a remote repository')
179
  .action((name, opts) => {
180
    console.log(`Removing remote ${name}`);
181
  });
182

183
// Optional base command (for help organization)
184
prog.command('remote')
185
  .describe('Manage remote repositories')
186
  .action((opts) => {
187
    console.log('Available remote commands: add, remove, list');
188
  });
189
```
190

191
### Default Commands
192

193
Set a command to run when no specific command is provided.
194

195
**Usage Examples:**
196

197
```javascript
198
// Set default via command options
199
prog.command('start [port]', 'Start the application', {
200
  default: true
201
});
202

203
// Now these are equivalent:
204
// $ my-cli start 8080
205
// $ my-cli 8080
206

207
// Without default command, this would show an error:
208
// $ my-cli 8080
209
// ERROR: No command specified.
210
```
211

212
### Command Context and State
213

214
Each call to `command()` changes the current command context. All subsequent configuration methods (`describe`, `option`, `action`, etc.) apply to the current command until another `command()` is called.
215

216
**Usage Examples:**
217

218
```javascript
219
const prog = sade('my-cli');
220

221
// Context switches to 'build' command
222
prog.command('build <src>')
223
  .describe('Build the application')  // applies to 'build'
224
  .option('-w, --watch', 'Watch mode')  // applies to 'build'
225
  .action((src, opts) => {});          // applies to 'build'
226

227
// Context switches to 'test' command  
228
prog.command('test [pattern]')
229
  .describe('Run tests')               // applies to 'test'
230
  .option('-c, --coverage', 'Show coverage')  // applies to 'test'
231
  .action((pattern, opts) => {});      // applies to 'test'
232
```