0
# Sade
1

2
Sade is a small but powerful tool for building command-line interface (CLI) applications for Node.js that are fast, responsive, and helpful. It enables default commands, git-like subcommands, option flags with aliases, default option values with type-casting, required-vs-optional argument handling, command validation, and automated help text generation.
3

4
## Package Information
5

6
- **Package Name**: sade
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install --save sade`
10

11
## Core Imports
12

13
```javascript
14
const sade = require('sade');
15
```
16

17
For ES modules:
18

19
```javascript
20
import sade from 'sade';
21
```
22

23
## Basic Usage
24

25
```javascript
26
const sade = require('sade');
27

28
const prog = sade('my-cli');
29

30
prog
31
  .version('1.0.5')
32
  .option('--global, -g', 'An example global flag')
33
  .option('-c, --config', 'Provide path to custom config', 'foo.config.js');
34

35
prog
36
  .command('build <src> <dest>')
37
  .describe('Build the source directory. Expects an `index.js` entry file.')
38
  .option('-o, --output', 'Change the name of the output file', 'bundle.js')
39
  .example('build src build --global --config my-conf.js')
40
  .example('build app public -o main.js')
41
  .action((src, dest, opts) => {
42
    console.log(`> building from ${src} to ${dest}`);
43
    console.log('> these are extra opts', opts);
44
  });
45

46
prog.parse(process.argv);
47
```
48

49
## Architecture
50

51
Sade is built around several key components:
52

53
- **Factory Function**: Creates new Sade instances for CLI programs
54
- **Command System**: Hierarchical command structure with subcommands and arguments
55
- **Option Parsing**: Flag and option handling with aliases and default values
56
- **Help Generation**: Automatic help text generation for commands and global usage
57
- **Action Handlers**: Callback functions executed when commands are invoked
58
- **Single Command Mode**: Simplified mode for single-purpose CLI tools
59

60
## Capabilities
61

62
### CLI Program Creation
63

64
Core factory function for creating CLI program instances with optional single-command mode.
65

66
```javascript { .api }
67
/**
68
 * Creates a new Sade CLI program instance
69
 * @param {string} name - The name/usage pattern of the CLI program
70
 * @param {boolean} [isSingle] - Enable single-command mode
71
 * @returns {Sade} Chainable Sade instance
72
 */
73
function sade(name, isSingle);
74
```
75

76
[Program Creation](./program-creation.md)
77

78
### Command Definition
79

80
System for defining commands with usage patterns, descriptions, and argument handling.
81

82
```javascript { .api }
83
/**
84
 * Define a new command with usage pattern and options
85
 * @param {string} usage - Command usage pattern with arguments
86
 * @param {string} [desc] - Command description
87
 * @param {object} [opts] - Options including alias and default
88
 * @returns {Sade} Chainable instance
89
 */
90
command(usage, desc, opts);
91

92
/**
93
 * Add description to current command
94
 * @param {string|string[]} text - Description text
95
 * @returns {Sade} Chainable instance
96
 */
97
describe(text);
98

99
/**
100
 * Define aliases for current command
101
 * @param {...string} names - Alias names
102
 * @returns {Sade} Chainable instance
103
 */
104
alias(...names);
105
```
106

107
[Command Definition](./command-definition.md)
108

109
### Options and Configuration
110

111
Option flag system with aliases, descriptions, and default values.
112

113
```javascript { .api }
114
/**
115
 * Add option flag to current command
116
 * @param {string} flags - Flag pattern (e.g., '-f, --force')
117
 * @param {string} [desc] - Option description
118
 * @param {*} [value] - Default value
119
 * @returns {Sade} Chainable instance
120
 */
121
option(flags, desc, value);
122

123
/**
124
 * Set program version
125
 * @param {string} str - Version string
126
 * @returns {Sade} Chainable instance
127
 */
128
version(str);
129

130
/**
131
 * Add usage example to current command
132
 * @param {string} str - Example usage string
133
 * @returns {Sade} Chainable instance
134
 */
135
example(str);
136
```
137

138
[Options and Configuration](./options-configuration.md)
139

140
### Action Execution
141

142
Action handler system for command execution and argument parsing.
143

144
```javascript { .api }
145
/**
146
 * Attach callback handler to current command
147
 * @param {function} handler - Command handler function
148
 * @returns {Sade} Chainable instance
149
 */
150
action(handler);
151

152
/**
153
 * Parse command line arguments and execute appropriate handler
154
 * @param {string[]} arr - Command line arguments (typically process.argv)
155
 * @param {object} [opts] - Parsing options
156
 * @returns {void|object} Void (executes handler) or LazyOutput if opts.lazy = true
157
 */
158
parse(arr, opts);
159
```
160

161
[Action Execution](./action-execution.md)
162

163
### Help System
164

165
Automated help text generation and display system.
166

167
```javascript { .api }
168
/**
169
 * Display help text for command or general help
170
 * @param {string} [cmd] - Command name for specific help
171
 * @returns {void} Prints to console
172
 */
173
help(cmd);
174
```
175

176
[Help System](./help-system.md)
177

178
## Types
179

180
```javascript { .api }
181
// TypeScript definitions for better IDE support
182
interface Sade {
183
  command(usage: string, description?: string, options?: CommandOptions): Sade;
184
  option(flag: string, description?: string, value?: Value): Sade;
185
  action(handler: Handler): Sade;
186
  describe(text: Arrayable<string>): Sade;
187
  alias(...names: string[]): Sade;
188
  example(usage: string): Sade;
189
  parse(arr: string[], opts: { lazy: true } & ParseOptions): LazyOutput;
190
  parse(arr: string[], opts?: { lazy?: boolean } & ParseOptions): void;
191
  version(value: string): Sade;
192
  help(cmd?: string): void;
193
}
194

195
interface CommandOptions {
196
  alias?: Arrayable<string>;
197
  default?: boolean;
198
}
199

200
interface ParseOptions {
201
  lazy?: boolean;
202
  alias?: Record<string, string | string[]>;
203
  default?: Record<string, any>;
204
  unknown?: (flag: string) => string | void;
205
  // Additional mri parsing options are also supported
206
}
207

208
interface LazyOutput {
209
  name: string;
210
  handler: Handler;
211
  args: string[];
212
}
213

214
type Handler = (...args: any[]) => any;
215
type Value = number | string | boolean | null;
216
type Arrayable<T> = T | T[];
217
```